Nova Devtool Laravel Package

Getting Started

Nova Devtool is not something you install in your Laravel application — it's a dev-only dependency for whoever maintains a Nova package (a card, tool, field, filter, or resource tool). If you only consume third-party Nova packages, this adds nothing. If you author one, it replaces the usual "install a whole throwaway Laravel app with Nova in it" ceremony.

Two installs, both dev-scoped:

composer require --dev laravel/nova-devtool
npm install --save-dev @laravel/nova-devtool

Then bootstrap a real Nova instance inside the package's workbench/ directory:

php vendor/bin/testbench nova:devtool setup
composer run serve

First place to look after setup runs: testbench.yaml at the package root and the generated workbench/ tree. That YAML is the whole control surface for the harness. The single highest-value tweak is auto-login, so you never have to type credentials into the workbench:

workbench:
  start: /nova
  user: [email protected]

Your first real use case should be: open /nova from composer run serve, confirm the Nova shell renders, then create a minimal resource or card in the workbench and prove the component's compiled assets are being picked up. Only then start on the component itself — debugging "my component doesn't appear" and "my workbench is broken" at the same time is miserable.

Also run php vendor/bin/testbench nova:devtool install early; it front-loads the frontend stack (Axios, Lodash, Tailwind, Vue) and patches package.json for you instead of you guessing at versions that match Nova's own build.

Implementation Patterns

Treat the workbench as disposable scaffolding, not an app. Everything under workbench/ exists to serve your component. Keep it out of your review diffs and be willing to delete and re-run nova:devtool setup when it gets weird. The composer run serve script it registers is your daily driver.

The build loop. Author the PHP side (Tool/Card/Field class + NovaServiceProvider registration) and the Vue side in the package's resources/js, build with Laravel Mix, and have the workbench consume the package as a path dependency. The devtool's job is that the workbench resolves your package's service provider automatically — so a change to src/ needs a workbench refresh, while a change to resources/js needs a Mix rebuild.

Use the Vue DevTool toggle as a debugging switch, not a permanent setting. Nova ships production-compiled Vue, so Vuex/Vue component inspection is dead by default:

php vendor/bin/testbench nova:devtool enable-vue-devtool
# ...debug reactive state, slots, props...
php vendor/bin/testbench nova:devtool disable-vue-devtool

Flip it on when a component's props or store state look wrong, then flip it back. Leaving it enabled slows the asset load and confuses anyone else running the package.

Standardize the webpack setup across your packages. Nova 4-era components each carried a copy-pasted nova.mix.js. The current pattern is one generic file provided by the devtool, wired in via mix.extend:

let mix = require('laravel-mix')

mix.extend('nova', new require('laravel-nova-devtool'))

mix
  .setPublicPath('dist')
  // ...

Do this migration on every package you maintain — it deletes a file per repo and means a Nova build-behavior change lands via a composer update, not a manual edit in N repos. If you keep a package on Nova 4, leave the old require('./nova.mix') alone until you upgrade.

TypeScript-aware packages: the tsconfig action (added in 1.2.0) writes a tsconfig.json without prompting. Prefer that over hand-authoring one so your compiler settings match what the devtool expects.

Generator commands exist (added in 1.5.0) for scaffolding Nova classes. If you're creating several fields/cards in a session, use them rather than hand-writing boilerplate — the generated namespace and provider wiring were fixed over several point releases and now come out correct.

Policy/authorization behavior: if your tool gates on policies, note 1.4.2 fixed Gate resolving the wrong Policy class in the workbench. If you're on anything older, authorization tests in the workbench will lie to you.

Gotchas and Tips

• Version-pin against Nova's minor version. Nearly every release is "Supports Laravel Nova 5.x." Nova's frontend internals move, and the devtool's Vue/Mix assumptions move with them. When you bump the Nova constraint in composer.json, bump the devtool in the same commit, and re-run npm install --save-dev @laravel/nova-devtool.
• NPM package name ambiguity is real. The install docs say @laravel/nova-devtool; the webpack.mix.js migration snippet references laravel-nova-devtool. A README typo fix landed in 1.8.13. Check what actually appeared in your package.json devDependencies before debugging a require() failure.
• The install command always rewrites package.json. Release 1.2.1 made it unconditionally register the devtool. Re-running it is safe but will clobber hand edits to those dependency entries — commit before you run it.
• enable-vue-devtool mutates Nova's distributed vendor assets. Those changes are not source, they're patched files under vendor/. A composer update or composer install will silently undo them; re-run the command after any dependency refresh, and never assume another developer's checkout has it on.
• This must never ship to production. It's --dev, it exposes a workbench with an auto-authenticated user, and it patches vendor code. If a release process ever runs composer install without --no-dev on a deploy target, you have a problem. Keep it out of require and out of any packaged distribution.
• php vendor/bin/testbench is the binary, not php artisan. Commands are nova:devtool setup, install, enable-vue-devtool, disable-vue-devtool. If testbench is missing, it's a transitive Orchestra Workbench install problem, not a devtool bug.
• composer run serve only exists after setup. If the script is absent, setup didn't complete — check that testbench.yaml was written and the workbench/ directory exists rather than adding the script by hand.
• Auto-login requires the exact user shape. workbench.user: takes an email that must exist in the workbench's seeded data; a typo silently lands you on the login screen rather than erroring loudly.
• Debugging inside the workbench: dump()/dd() work normally in your package's PHP, but because the workbench is a separate app root, stack traces point at workbench/vendor/.... Set a breakpoint or log to workbench/storage/logs/laravel.log rather than reading the browser output.
• Extension point: the generic nova.mix.js is the intended customization seam — if you need extra Mix behavior across all your Nova packages, extend there rather than forking per package. MetricBehavior (fixed in 1.8.4 for a missing uid/single) is where Nova's metric card conventions live if you're building metric-adjacent components.
• Low adoption, single maintainer. 33 stars and essentially zero dependents means you are the QA. Pin the exact version ("laravel/nova-devtool": "1.10.2"), read the release notes before every bump — they're terse but they tell you exactly which Nova minor is supported — and expect the occasional "supports Nova 5.7.4" patch release to be the only fix for a build break.