Nova Assets Versioning Laravel Package

Getting Started

This package does one narrow job: it lets you append a cache-busting version marker to Nova's compiled CSS/JS URLs so that browsers and proxies fetch fresh admin assets after a Nova upgrade or a custom tool rebuild. That is the entire day-to-day value; treat it as infrastructure glue, not a feature package.

Because the repository is archived, your first stop is the README's "maintained alternatives" note, not the code. If you still proceed:

1. Pin the exact version in composer.json ("norman-huth/nova-assets-versioning": "x.y.z") — an archived package with 0 dependents will not receive Nova/PHP compatibility patches.
2. Install and publish the config (confirm the tag in the README; typically php artisan vendor:publish --tag=nova-assets-versioning-config).
3. Open config/nova-assets-versioning.php first. That file is the whole API surface: an enable switch and the version value/source. Read the service provider next to see exactly which Nova asset URLs it rewrites.
4. Set a version and load /nova in a private window. Your first use case is the canonical one: a Nova upgrade ships, users report "the admin looks broken," and you bump the version so their cached JS/CSS is replaced without asking them to hard-refresh.

Verify the result in the rendered HTML (<script src=".../nova-api/scripts/...?v=...">) and in the Network tab, not in the source.

Implementation Patterns

Environment-driven version string. The simplest reliable pattern is an env value that changes on every deploy:

NOVA_ASSETS_VERSION=${GIT_SHA}

Set it from your deploy script (Git SHA, build number, or release tag). A stable value per release means the query string changes exactly when assets might have changed — no gratuitous cache misses and no stale assets.

Content-derived version. If the package supports deriving the version from the published Nova directory (filemtime or hash), prefer a content hash over mtime: mtime is unreliable across rsync --times, symlink-swapped releases, and container image layers. If only mtime is offered, use a hash you compute yourself and feed it in via config.

Deploy hook. Wire the version bump into the same step that runs php artisan nova:publish and php artisan config:cache. A version bump that happens before config:cache is silently discarded because the cached config wins at runtime.

Custom tools, cards, and fields. Nova tool/card/field assets are registered through Nova's own script/style helpers. Confirm the package patches those URLs too (it hooks Nova's asset registration, not arbitrary <script> tags), and test one custom card after a rebuild — that is where stale assets actually bite, since third-party tool JS is the usual culprit for "works for me, broken for the client."

CDN/proxy alignment. Query-string busting only helps if your CDN and any reverse proxy include the query string in the cache key (Cloudflare does by default; some S3/CloudFront and nginx configurations strip or ignore it). Where you control the origin, purge the /nova-api/scripts/* and /nova-api/styles/* paths on deploy in addition to versioning — belt and braces.

Local vs production. Disable versioning locally if you are watching Nova tool assets with npm run watch; a fixed version string plus a long browser cache is a debugging tax. Keep it on in staging so you exercise the same path as production.

Gotchas and Tips

• Archived = you are the maintainer. Expect the package to break on a future Nova major or PHP minor. Before adopting, diff the service provider against Nova's current asset registration; a 20-line middleware or Nova::script/Nova::style override may be a cheaper, safer replacement than a dead dependency.
• Config caching. After changing the version in .env, run php artisan config:clear (or re-run config:cache) — otherwise you will "prove" the package does nothing while staring at a stale cached config.
• Query strings don't beat immutable + long max-age in every cache. Some intermediaries and older proxies ignore query strings for cache keying. Check the actual Cache-Control/ETag headers with curl -I against your deployment before assuming the problem is solved.
• Hardcoded asset paths bypass it entirely. Any Blade view, custom layout, or third-party package that writes /nova-api/scripts/foo directly will not be versioned. Grep your codebase for those paths during rollout.
• Conflicts with other Nova asset packages. If another package also rewrites Nova asset URLs or overrides the same route/service binding, load order decides the winner. Check composer show and php artisan about and test with the other package disabled.
• Debugging checklist: view rendered HTML for the ?v= parameter → confirm the config value at runtime (php artisan tinker, config('nova-assets-versioning')) → confirm no config cache → check response headers → test in a private window. If the parameter never appears, the service provider is almost certainly not registered (package discovery disabled, or a dont-discover entry).
• Extension points are thin. You can override the config, but the real extension point is forking the provider. If you fork, keep the same config key names so your .env and deploy scripts survive the switch.
• Prefer native/standard alternatives if they fit: Nova's own versioning plus Vite/Mix manifest hashing on your tool assets usually removes the need for a third-party cache-buster. Adopt this package only if you specifically need to version Nova's core assets and have no control over the deploy-time versioning story.