Nova Translation Laravel Package

Getting Started

• Install the package: composer require <vendor>/<package>:"^2.0". Version 2 is the Nova 4 line — do not attempt to install it into a Nova 3 app.
• Requirements first: Nova 4 means PHP 8.1+, Laravel 9/10+, and Inertia/Vue 3 on the frontend. Confirm your app meets these before touching the package, since Composer will otherwise fail or, worse, resolve a mismatched dependency tree.
• Register it where Nova expects it:
  • Cards/tools/fields go in app/Nova/NovaServiceProvider.php (cards(), tools(), fields(), or dashboards()).
  • Tools typically also need php artisan nova:publish or the package's own publish tag so compiled assets land in public/vendor/<package>.
• Publish config (if provided): php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" and check config/<package>.php for feature toggles, route prefixes, and middleware.
• First use case: add the card/tool/field to a single Nova resource or the main dashboard, hit /nova, and confirm it renders. Only then wire it into multiple resources — this isolates asset-pipeline problems from configuration problems.

Implementation Patterns

• Resource-level integration: for a field, add it to fields() on the relevant Nova resource; for a card, add it in cards() on a resource or NovaServiceProvider::cards() for the dashboard. Prefer resource-level scoping when the data is model-specific.
• Dashboard cards: keep cards() declarative — instantiate with options rather than reading request state inside the card, so cards remain cacheable and testable.
• Tools as self-contained screens: register the tool in tools(), then use the package's routes/controllers for data endpoints. Keep authorization in the tool's authorize() or a policy rather than in the Vue component.
• Metable/option-driven fields: resolve field options server-side (resolve() / fields() callbacks) and pass primitives to the frontend. This keeps N+1 queries out of the Nova request cycle.
• Index vs. detail behavior: many Nova components behave differently in Index (table cell, no full model) and Detail views. Test both; use ->onlyOnDetail() / ->hideFromIndex() where the component assumes a loaded model.
• Composing with existing Nova features: combine with CanSee, CanBeSeen, and metric filters instead of building parallel visibility logic in the package config.
• Local development loop: npm run watch inside the package (or nova:dev) while pointing the app's composer.json at a path repository, so frontend changes hot-reload without republishing assets each time.

Gotchas and Tips

• v2.0.0 is a hard break from Nova 3. Nova 4 moved to Vue 3 + Inertia and dropped Vue 2 mixins/Vue.component registration. If you have custom Nova components that depended on this package's v1 frontend hooks, they will not carry over. Pin ^1.0 on any Nova 3 app that still needs it.
• Asset staleness is the #1 false bug report. After upgrading, run php artisan nova:publish --force and clear public/vendor/<package>, then hard-refresh. Half-broken rendering is almost always old compiled assets.
• Version constraint conflicts: Nova 4 itself is a private Composer package. Ensure your nova constraint and the package's nova constraint overlap; otherwise you get an unresolvable dependency error that looks like a package bug.
• Authorization: Nova 4 tightened gate checks. If a tool or card silently disappears, check Gate::define / policies and the tool's authorize() before assuming a rendering bug.
• Caching: config and route caches (config:cache, route:cache) will hide newly published config and registered routes. Clear both after any publish step.
• Queues and long-running work: if the package exposes metrics or exports, confirm whether it dispatches jobs — Nova requests are still web requests and will time out on heavy synchronous queries.
• Extension points: prefer the package's published config and documented events/hooks over subclassing internal classes. Nova 4's internal API churn means subclassed internals are the most likely thing to break on the next minor release.
• Debugging frontend issues: use the browser console and Nova's own nova:dev tooling; because the frontend is Inertia-driven, network tab inspection of the /nova-api calls usually reveals whether the problem is server-side resolution or component rendering.
• Upgrade checklist: bump the constraint, republish config and assets, re-run Nova's authorization tests, and smoke-test every resource that uses the package — not just one — since Nova 4 changed how fields resolve on index endpoints.