Getting Started

This release is a Nova 5 compatibility drop. Treat it as a fresh install rather than an in-place bump — there is no prior assessment to diff against, and Nova 5 itself is a major version, so the package's own v1.0.0 is effectively the first stable line for that Nova generation.

Minimal path:

Confirm your app is already on Nova 5 (composer show laravel/nova), plus the Laravel/PHP versions Nova 5 requires. If you are still on Nova 4, do not install this — pin the previous package line instead.
composer require <vendor>/<package>:^1.0 (Nova is a private package, so your nova.laravel.com Composer credentials must be configured on every machine and in CI).

Publish what the package ships:

php artisan vendor:publish --provider="Vendor\Package\ToolServiceProvider" --tag=package-config
php artisan vendor:publish --provider="Vendor\Package\ToolServiceProvider" --tag=package-assets

Register the artifact in app/Providers/NovaServiceProvider.php — the method depends on what the package ships:
```
public function tools(): array
{
    return [
        new \Vendor\Package\PackageTool(),
    ];
}
```
Cards go in cards(), custom fields in the fields() method of a Resource, filters in filters().

Where to look first: the package's src/ for the registered Tool/Card/Field class and its canSee/authorize methods, then its resources/js (or dist/) to confirm compiled assets are committed. Read the package's own upgrade note for Nova 5 before anything else — that is the only changelog signal you have for this release.

First use case: add it as a dashboard card or a tool in the sidebar, hit /nova, and confirm it renders before wiring it into Resources. That isolates asset/registration failures from field-level failures.

Implementation Patterns

Artifact-type driven integration. Nova packages are rarely one thing. Check whether v1.0.0 exposes a Tool (sidebar entry), Card (dashboard metric), Field (resource form/detail), Filter, Action, or Lens — each registers in a different place. Don't assume tools(), a cards() entry is more common for dashboard widgets.
Constructor configuration over config files. Nova tools/cards typically take options in the constructor:
```
public function cards(): array
{
    return [
        (new \Vendor\Package\MetricCard())->width('1/2')->refreshWhenActionRuns(),
    ];
}
```
Keep app-specific values (API keys, model classes, thresholds) in config/ and resolve them in the package's service provider rather than passing raw values around the dashboard.
Per-user visibility. Use canSee(Request $request) for UI-level hiding and authorize(Request $request) for hard enforcement. Pattern: admin-only metrics via canSee, data-scoped queries via policy checks inside the card's calculate().

Resource field pattern (if the release ships a Field):

public function fields(NovaRequest $request): array
{
    return [
        \Vendor\Package\PackageField::make('Setting')
            ->rules('required', 'max:255')
            ->onlyOnForms(),
    ];
}

Always test resolve() (index/detail) and fill() (create/update) separately — Nova 5 render changes tend to break the display path first.

Local dev loop for frontend assets. If you're modifying the package's Vue components, run the package's build (npm ci && npm run prod in the package directory, or its nova:install equivalent), then republish assets. Commit or re-publish dist/ after every change or Nova will serve stale JS.
Testing. Use Nova's testing helpers (Nova::actingAs(), Nova::json()/Nova::get()) to assert the tool/card appears for the right users and is absent for others. A cheap regression suite here pays for itself across future Nova bumps.
Composer hygiene in a monorepo. If multiple apps share this package, keep the constraint as ^1.0 and let a path repository point at a checkout during development; Nova packages go stale fast because the ecosystem's floor moves with each Nova major.

Gotchas and Tips

Nova 5 is the only supported target. A v1.0.0 cut whose headline is "Update for Laravel Nova 5" almost always raises the floor and drops Nova 4 support. Check composer.json for "laravel/nova": "^5.0" and a conflict/provide block before upgrading an existing app. There is no graceful coexistence — you upgrade Nova and the package together.
Compiled assets are the #1 failure mode. Nova caches published assets aggressively. After install or upgrade: republish assets, hard-refresh the browser, and if the UI is blank check the browser console before touching PHP. A white card is nearly always a JS bundle mismatch, not a backend error.
Version-string cache busting. Custom tools usually register assets with a Nova::script(..., $version) call. If the package hardcodes a version, bumping it yourself after local asset changes is the only way to beat browser caching.
Private Composer auth in CI. Nova 5 pulls laravel/nova from nova.laravel.com; a fresh CI runner without credentials fails at composer install with a confusing 401. Verify the auth config before debugging the package.
canSee is not security. Both canSee and authorize are UI gates by default. If the card/field exposes data through a JSON endpoint, enforce the same policy in the controller — Nova's endpoint is routable by anyone with a session.
Dark mode and layout. Nova 5 tightened its design tokens. Custom tool components that hardcoded hex colors or relied on the old grid classes often render poorly. Test dashboard cards at the small breakpoint and in dark mode.
php artisan nova:publish vs vendor:publish. The package's own tags may be missed if you only run the Nova command. Run both, and re-run after upgrades.
Extension points worth knowing: Nova::script()/Nova::style() for asset injection, the package's Tool boot()/renderNavigation() methods for menu customization, and Nova::resources()/resourcesIn() for auto-discovery — the last one can silently hide registered resources if a namespace is wrong.
Deprecation watch. Since this is the first v1.0.0, expect the next minor to be the real API stabilizer. Pin with ^1.0 for libraries, 1.0.* for production apps you don't test continuously, and keep an eye on the package's Nova 5 issues as other users shake out the bump.

Nova 4 Slack Channel Field Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips