Nova View Laravel Package

Getting Started

Install

composer require <vendor>/<package>
php artisan nova:publish      # or: vendor:publish --tag=nova-<package>-assets

You need laravel/nova installed and a valid Nova license/credentials (composer config http-basic.nova.laravel.com <email> <license-key>) before Composer can resolve anything that depends on Nova.

Where to look first

1. composer.json of the package — check the require block and any extra.laravel.providers auto-discovery entry.
2. The package's service provider — look for Nova::tools(), Nova::cards(), Nova::fields(), or Nova::script()/Nova::style() calls. That tells you whether it's a tool, card, or field and how it hooks in.
3. resources/js/ and routes/ — the Vue entrypoint and any backend endpoints the component calls.
4. config/ — whether it publishes a config file (php artisan vendor:publish --tag=<package>-config) and what's optional.

First use case

Register it in app/Providers/NovaServiceProvider.php and immediately exercise the happy path on one resource or one dashboard before wiring it anywhere broad:

// tools() — for a tool/card surfaced in the sidebar
public function tools()
{
    return [
        new \Vendor\Package\MyTool(),
    ];
}

// fields() — for a field used inside a resource
public function fields(Request $request)
{
    return [
        ID::make()->sortable(),
        \Vendor\Package\MyField::make('Status'),
    ];
}

Then hit /nova and confirm the component renders before you start configuring it.

Implementation Patterns

Fields — the resource-local pattern. Instantiate inside fields() per resource so each resource controls visibility and formatting:

MyField::make('Score')
    ->rules('required', 'integer', 'min:0')
    ->onlyOnDetail()          // or ->hideFromIndex(), ->sortable()
    ->default(0);

If the field persists data, verify fill()/resolve() behave through a create → update → reload cycle; if it's display-only, use ->exceptOnForms().

Tools and cards — the global pattern. Register once in NovaServiceProvider::tools()/cards() and guard access with ->canSee(fn ($request) => ...) or a Nova gate rather than filtering in the component. Prefer policy checks over role strings:

(new MyTool)->canSee(fn (Request $request) => $request->user()->can('viewReporting'));

Frontend work loop. The package ships compiled assets. If you need to modify them, use the standard Nova component loop:

npm install
npm run dev        # or: npm run watch
php artisan nova:publish --force

Keep the --force in your loop; without it, republished assets silently keep the old bundle and you'll debug phantom behaviour.

Backend endpoints. If the package registers routes, they land under Nova's route group and inherit Nova's middleware. Confirm the prefix and auth middleware with:

php artisan route:list | grep -i nova

Namespace any of your own endpoints under the same group so you inherit Authorize and Nova's Authenticate middleware instead of reimplementing them.

Testing. Nova components are awkward to test end-to-end. For fields, assert against the model and resource definition rather than the Vue layer; for tools, use Nova's Nova::actingAs()-style test helpers or plain feature tests against the tool's route with an authenticated user. Prefer asserting the authorization boundary (403 for a user without the gate) over asserting rendered markup.

Composer constraint hygiene (v1.1.0). The package no longer requires laravel/framework or illuminate/* directly — it now inherits them transitively from laravel/nova. Before upgrading existing projects, run:

composer why laravel/framework
composer why laravel/nova
composer update <vendor>/<package> --with-dependencies

This release is not breaking for a normal Nova install; it only tightens the dependency graph. The failure mode is a project that installed the package without Nova present — that no longer produces an explicit framework conflict, so a missing-Nova setup can now resolve and then blow up at runtime with a class-not-found on Laravel\Nova\*.

Gotchas and Tips

Asset cache-busting is the #1 source of "my change didn't apply." Nova serves versioned asset URLs computed from the manifest. After composer update or a manual rebuild, always php artisan nova:publish (with --force for local dev), and hard-refresh the browser. If a component loads but renders blank, open the console for a 404 on a hashed JS filename — that's the manifest being stale, not a code bug.

Version coupling with Nova majors. This package is only loosely pinned to Nova. Nova 4 → 5 changed the component build (laravel-mix → Vite, Vue 3) and layout conventions. Before a Nova major upgrade, check the package's compatibility notes rather than assuming the transitive dependency is sufficient — a resolved install is not a working install.

The dropped framework requirement means your constraint, not theirs, wins. If you have a project pinning laravel/framework to an older minor, the package will no longer complain; you'll instead get runtime errors deep in Nova. Pin Nova explicitly in composer.json ("laravel/nova": "^4.0") so the real constraint is visible.

Authorization belongs server-side. canSee() hides the nav item; it does not protect a route the component calls. Any endpoint the package registers must have its own authorize/policy check, and your own additions to the tool must follow suit. Test this with a low-privilege user rather than reasoning about it.

Config publishing order. If the package publishes both config and assets, publish config first, then clear config cache (php artisan config:clear) — a cached config from before the publish will make new keys look ignored.

Debugging an empty Nova page. In order: (1) storage/logs/laravel.log for a PHP fatal in the provider, (2) browser console for a JS 404, (3) php artisan route:list | grep nova to confirm the tool registered, (4) Nova::tools() return value in a tinker session for authorization filtering. That sequence isolates provider-error vs asset-error vs auth-filter in four steps.

Extension points. Rather than editing the package's Vue files (which vanish on composer update), override at registration time — subclass the tool/card, wrap the field, or pass constructor/config options. If the package doesn't expose what you need, that's the upstream issue to file; local patches in vendor/ will be lost and are a recurring source of "it worked on my machine" bugs.