Getting Started

Treat v1.0.0 as the first Nova 4-compatible release. Before installing, confirm the package’s README constraints against your app: Nova 4, a compatible Laravel version, and PHP 8+ where required by your Nova installation.
Install with Composer, then publish any package config, migrations, views, translations, or assets using the commands documented by the package. Register the package’s Nova tool, card, field, resource, or service provider in app/Nova/NovaServiceProvider.php or via the package’s documented registration hook.
First use case: add the package to a local or staging Nova dashboard and exercise the primary workflow end-to-end—render the UI, load data, submit an action/form, and confirm authorization behaves correctly for an admin and a non-admin user.
Look first at: the package README, CHANGELOG, config/, src/, routes/, resources/js/, and any published Nova components. For an upgrade from a Nova 3-oriented version, start with the upgrade notes and any Vue 3 / asset-pipeline changes.

Implementation Patterns

Register the package in Nova’s service provider rather than wiring routes or menus manually unless the package explicitly supports that. Keep Nova tool/card/field registration close to the related resource or dashboard.
Publish configuration and keep environment-specific values in .env. Run php artisan config:cache only after verifying the package reads config at runtime, not during bootstrap in a cache-sensitive way.
For day-to-day use, treat the package as part of your Nova admin surface: combine it with Nova policies, gates, canSee/canRun callbacks, filters, actions, and metrics where applicable.
If the package ships frontend assets, use its documented build/publish flow. For customizations, publish the views/components first, then rebuild assets with the package’s supported npm/Vite workflow rather than editing vendor files.
In tests, cover Nova authorization and the package’s HTTP endpoints or actions with feature tests. For UI-heavy behavior, use a focused browser test or manual staging checklist rather than relying only on unit tests.
When upgrading from Nova 3, audit custom cards/tools/fields for Vue 3 compatibility, changed registration APIs, route/menu behavior, and asset compilation. Keep the Nova 4 package version pinned and upgrade Nova and the package together.

Nova 4 is a breaking platform upgrade for many custom Nova extensions: Vue 3, updated frontend tooling, and changed APIs can break Nova 3-era components. Do not assume existing custom cards, tools, or fields work unchanged.
Re-publish and rebuild assets after upgrading. Clear Laravel and Nova caches, then run the package’s documented publish/build commands; stale compiled assets are a common source of blank or broken Nova UI.
Config caching can hide changes. Run php artisan config:clear after editing package config, and confirm the package does not depend on runtime-only config values.
Authorization is easy to miss. Verify the package respects Nova policies and canSee/canRun callbacks; test as a non-admin user before shipping.
Debugging order: check storage/logs/laravel.log, browser console/network errors, php artisan route:list for package routes, and Nova’s published assets. For frontend issues, confirm the correct asset entry point is loaded.
Extension points are usually published config, views, translations, and frontend components. Prefer these over modifying vendor/ so future Composer updates remain safe.
Because v1.0.0 is an initial Nova 4 release, treat it as a compatibility baseline: validate in staging, back up data before running migrations, and keep a rollback path for both the package and Nova.