Getting Started

Confirm your stack: this 2.0.0 release adds Nova v4 support. Nova 4 generally requires a modern Laravel/PHP baseline, so check the package’s composer.json constraints before upgrading. If you are still on Nova 3, stay on the package’s 1.x line.
Install or upgrade:
```
composer require vendor/package:^2.0
```

Publish any package assets/config if the package provides them:

php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"

Register the package where Nova expects it:
- Tools: add to app/Providers/NovaServiceProvider.php in tools().
- Fields: add the field class inside a Nova resource’s fields() method.
- Cards: add to the dashboard or resource cards() method.
First use case: open the Nova dashboard and verify the tool/card appears; or add the package’s field to a resource and confirm it renders on the index and detail screens.
Where to look first: the package README for Nova 4 setup, UPGRADE.md/CHANGELOG.md for 1.x → 2.x notes, config/package.php for options, and the package service provider for registration hooks.

Implementation Patterns

public function tools()
{
    return [
        new \Vendor\Package\Tool,
    ];
}

Use package fields directly in resources:

use Vendor\Package\Field;

public function fields(Request $request)
{
    return [
        Field::make('Name')->sortable(),
    ];
}

Add cards to dashboards or resources:

public function cards()
{
    return [
        new \Vendor\Package\Card,
    ];
}

If you maintain resources across Nova versions, guard v4-only APIs with Nova::version() or keep separate branches/constraints. Do not load v4-only classes on Nova 3.
Upgrade workflow: bump to ^2.0, run php artisan nova:publish if Nova assets need refreshing, run any published migrations, then clear caches.
Treat configuration as application config: publish the package config, commit it, and drive behavior through env/config rather than editing vendor files.
For custom tool endpoints, keep controllers and authorization in your app’s namespace where possible; inject services instead of putting business logic in the tool class.
Add feature tests around Nova routes and resource behavior. Assert tool visibility with the package or Nova testing helpers, and verify authorization paths for non-admin users.

2.0.0 is a major release. Assume Nova 3 support was dropped. If you cannot upgrade Nova yet, pin the previous major version.
Nova 4 uses a newer frontend stack than Nova 3. Custom scripts/styles or tools built for the old Nova frontend may break; use the package’s published assets and avoid mixing v3-built assets.
After upgrading, run php artisan optimize:clear. Stale config, route, and view caches are a common reason a Nova tool or field “disappears.”
If installation fails, inspect constraints with:
```
composer why-not vendor/package 2.0.0
```
Nova 4 compatibility often conflicts with older Laravel/PHP versions.
Verify authorization: Nova tools, cards, and fields commonly support canSee/authorize callbacks. If an item is missing for a non-admin, check gates and policies before assuming the package is broken.
Debug with storage/logs/laravel.log, php artisan route:list --path=nova, and the browser network tab. Inertia/Vue asset 404s usually point to unpublished or stale Nova assets.
Review any package migrations before running them in production; Nova tools sometimes add their own tables.
Extension points generally include the package service provider, Nova::script/Nova::style, menus, custom tool routes, and published config. Prefer config overrides and your own service provider over modifying vendor code.