Nova Targomaan Laravel Package

Getting Started

This release is a Nova 4 compatibility bump, so the first job is confirming which Nova major you are on before you touch anything else.

1. Check the dependency contract. Open the package's composer.json and confirm it now requires laravel/nova: ^4.0 (and by extension PHP 8.0+/Laravel 9+). If your app is still on Nova 3, stay on the previous package major — v2.0.0 will not install or will install and break at runtime.
2. Install and publish.

   composer require <vendor>/<package>:^2.0
   php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
   php artisan nova:publish
   

3. Build or verify assets. Nova 4 tools ship Vite-compiled assets instead of Laravel Mix output. Check for dist/ (prebuilt, committed) versus a vite.config.js + package.json you must build yourself:

   cd vendor/<vendor>/<package>
   npm ci && npm run build
   

4. Register the tool/field in app/Providers/NovaServiceProvider.php (tools() for a tool, Nova::resources()/field list for a field) exactly as the package README shows — the registration API is unchanged, but the asset-loading call inside the package's service provider now points at Vite output.
5. First use case: mount it on a single Nova resource or the main dashboard and load /nova in the browser with APP_DEBUG=true. A correctly wired Nova 4 package shows no console errors and, for tools, renders its menu entry and Inertia page on first click. That smoke test surfaces 90% of upgrade problems immediately.

Where to look first when something is off: the package's service provider (asset paths, Nova::script/Nova::style), resources/js/ (Vue 3 components), routes/api.php (tool endpoints), and dist/ or vite.config.js (build artifacts).

Implementation Patterns

Tools and cards. Register in NovaServiceProvider::tools() / cards(). Nova 4 tools render through Inertia, so the package's entrypoint will reference a page component under resources/js/pages. Custom navigation lives in the tool's menu()/boot() rather than the old Nova::script bootstrapping alone.

Custom fields. The field lifecycle is unchanged (resolve, fill, withMeta, meta()), which is the easy part of this upgrade. What changed is the front-end: field components are Vue 3 + Inertia. Pass data down through meta() and consume it as props; keep any Axios calls on the tool's routes/api.php endpoints behind the nova middleware so auth and Nova's route prefix apply automatically.

Asset registration. The pattern is still:

Nova::script('vendor-package', __DIR__.'/../dist/js/tool.js');
Nova::style('vendor-package', __DIR__.'/../dist/css/tool.css');

Only the source of those files (Vite instead of Mix) and the manifest lookup changed. If you fork or extend the package, mirror this rather than loading assets from a Blade view.

Integration into existing resources. Attach fields in fields() as usual; for tools, use Nova::mainMenu() or the dashboard to surface them. If you wrap the package in your own policy/permission layer, do it in the service provider's boot() with Nova::when()-style gates rather than editing vendor code.

Local development loop. When iterating on the package's Vue components, run npm run dev (or npm run watch) inside the package directory and keep php artisan serve running. Nova 4's Vite setup supports hot reload; the old npm run watch + mix-manifest.json flow does not.

Testing. Use Nova::actingAs($user) for HTTP-level tests of any tool API routes. For the UI, Laravel Dusk still works, but ensure your Dusk setup targets the Vue 3 build — selectors tied to Vue 2 internals (e.g. __vue__ inspection) will not hold.

Gotchas and Tips

• Major-version lockstep. v2.0.0 is Nova 4 only. Pin laravel/nova and the package together in composer.json; a stray composer update on a Nova 3 app can resolve the package to v2 and fail at install or, worse, at boot.
• Stale Mix artifacts. Leftover mix-manifest.json or old public/vendor/<package> files will be served in preference to the new Vite output in some setups. Delete public/vendor/<package> and re-run php artisan vendor:publish --force after upgrading.
• Duplicate Inertia/Vue copies. Nova 4 bundles its own Inertia and Vue 3. If the package's package.json pins a different Inertia minor, you get blank tool pages or "page not found" console errors. Align with Nova's versions and dedupe (npm ls vue @inertiajs/inertia).
• Vue 2 → 3 component breakage. If you have customised or extended the package's components, watch for removed filters, beforeDestroy → beforeUnmount, $listeners merged into $attrs, and v-model semantics on custom components.
• Blank page debugging. With APP_DEBUG=true, check the browser console first, then storage/logs/laravel.log. A missing Vite manifest usually throws "Vite manifest not found"; a bad asset path in Nova::script shows as a 404 in the network tab.
• Rebuild after every pull. Because assets may be committed or built locally, document in your deploy pipeline whether npm ci && npm run build runs for this package. Silent stale assets after a deploy are the most common "it works locally" failure here.
• Caching layers. After upgrading run php artisan nova:publish, php artisan optimize:clear, and clear any CDN cache for /nova assets; Nova 4's hashed Vite filenames make stale-cache issues look like code bugs.
• Extension points to prefer. Use Nova::script/Nova::style, Nova::provideToScript (for bootstrapping config into the front end), and the tool's boot()/menu() methods rather than patching vendor files — those are the seams that survived the Nova 4 transition and will survive the next one.
• Deprecation watch. Anything the package does with Laravel\Nova\Tool::script-style legacy helpers or Mix-based build config is a candidate for removal in a future major; if your integration depends on it, isolate it behind your own wrapper now.