Nova Package Bundler Command Laravel Package

Getting Started

What this is, day-to-day. A dev-only Artisan command that scans your installed Nova packages, pulls their frontend assets out, and concatenates them into a single file (or a small set of files) that Nova loads instead of dozens of individual <script>/<link> tags. It does nothing at runtime — it's a build/deploy step. Every benefit you get from it is measured in reduced network requests on first Nova page load.

Install it in a scratch branch first.

composer require --dev fidum/nova-package-bundler-command
php artisan list | grep nova        # confirm the command name in your version
php artisan nova:bundler --help     # read the signature before running it

Two things to settle before you integrate it anywhere:

1. The exact command signature (nova:bundler vs a namespaced variant) — --help is authoritative for your pinned version.
2. Whether it writes to a configurable path or a hardcoded one — if there's a publishable config, php artisan vendor:publish --provider="Fidum\NovaPackageBundler\..." will reveal the destination.

If you want certainty in two minutes rather than two hours, read vendor/fidum/nova-package-bundler-command/src/. It's a small command class; the whole surface area fits on a couple of screens.

First use case — measure before you commit. Do not run this on a branch with uncommitted work; it writes files.

# 1. Baseline: open Nova in the browser, hard reload, record
#    - number of JS/CSS requests
#    - DOMContentLoaded / Load timings
#    - total transferred bytes

# 2. Bundle
php artisan nova:bundler

# 3. Inspect what changed
git status --short
git diff --stat

# 4. Clear the usual caches and hard reload
php artisan config:clear && php artisan view:clear
php artisan nova:publish --force   # only if your setup needs it

# 5. Re-record the same numbers

If the request count dropped materially and the Nova UI still works — tools, cards, fields, modals, resource forms — you've got a keeper. If nothing changed, you either have too few Nova packages installed for the merge to matter, or the command is doing something other than what you assumed. Both are answers; act on them.

Where the value actually lives. This scales with the number of Nova packages you have installed, not with app size. One tool installed shows nothing. A dashboard with eight third-party Nova packages is where the request-count win becomes visible.

Implementation Patterns

Post-update hook — the default integration. The bundle goes stale every time a Nova tool is added, upgraded, or removed, because the bundled contents are the installed versions of those packages' assets. Wire the command to fire automatically after Composer changes dependencies:

{
  "scripts": {
    "post-update-cmd": [
      "@php artisan nova:bundler"
    ],
    "post-install-cmd": [
      "@php artisan nova:bundler"
    ]
  }
}

Caveat: post-install-cmd runs in environments where Nova itself may not be installed yet (CI image builds, fresh clones). If the command throws there, move it to post-update-cmd only, or guard it:

"post-update-cmd": [
  "@php -r \"file_exists('vendor/laravel/nova') && passthru('php artisan nova:bundler');\""
]

Deploy pipeline placement. The bundler must run after composer install and before any step that reads or publishes Nova's asset manifest. A typical ordering:

composer install --no-dev --no-interaction --optimize-autoloader
php artisan nova:bundler
php artisan nova:publish --force
php artisan config:cache && php artisan route:cache && php artisan view:cache

If you reorder this so the bundler runs after nova:publish, you'll be editing files the publish step already copied — a classic silent-no-op.

CI drift guard. If the bundle output is committed (reasonable for small teams that want reproducible deploys), make CI fail when someone bumps a Nova tool and forgets to re-bundle:

- run: composer install --no-interaction
- run: php artisan nova:bundler
- run: git diff --exit-code -- 'public/vendor/**' 'dist/**'

Drop that last line if your output is generated fresh on every deploy and never committed — otherwise you'll be failing builds for a condition you don't care about.

Local development workflow. The rhythm is: composer require a new Nova tool → run php artisan nova:bundler → hard-reload Nova → verify the tool works. Add it to whichever shell alias or Make target you already use for "I just changed dependencies":

nova-refresh:
	php artisan nova:bundler
	php artisan config:clear
	php artisan view:clear

Cache busting on the merged file. A consolidated bundle sits at a stable path, so browsers will happily serve a stale copy after you deploy a new Nova tool version. Options, in order of preference:

• If the command emits a content-hashed filename, reference that (requires dynamic registration — more moving parts).
• Otherwise, version the URL at registration time with your app's release constant:

Nova::script(
    'nova-bundle',
    __DIR__.'/../public/vendor/nova-bundle.js?v='.config('app.asset_version'),
    null,
    ['defer' => true]
);

Bump app.asset_version on each release. Cheap, and it eliminates the entire "works for me, broken for the client" class of bug.

Rollback pattern. Keep the revert to one line. Before merging, note in the PR description:

Rollback: composer remove --dev fidum/nova-package-bundler-command
          rm -rf public/vendor/nova-bundle*
          git checkout -- composer.json composer.lock

Because the dependency is --dev and never touches the request lifecycle, this is genuinely all it takes. Confirm that's true on your install before you rely on it.

Gotchas and Tips

Stale bundles are the #1 failure mode. A Nova tool's compiled JS ships inside the package. When that package updates, the JS changes, and your merged bundle no longer matches. Symptom: a specific tool renders but its interactivity is dead, or the browser console shows a component registration error. Fix: re-run php artisan nova:bundler and hard-reload. Prevent: the Composer hook above.

Load order becomes global. Once multiple packages' scripts are concatenated into one file, ordering is no longer isolated per package. Two Nova tools that each register a Vue component with the same name, or that depend on a global shim being defined first, can collide. The failure is a console error or an inert component — never a build error. If you hit this, narrow the bundle (exclude the offending package if the tool supports it) rather than debugging the merge itself.

Cache layers, in order. After every bundling run, clear these before concluding anything is broken:

php artisan config:clear
php artisan view:clear
php artisan nova:publish --force    # if assets are published
php artisan optimize:clear          # nuclear option, clears everything

Then hard-reload the browser (devtools open, "Disable cache" ticked). A surprisingly large fraction of "the bundler broke Nova" reports are one of these caches.

404s on the bundle path mean nova:publish ran at the wrong time or wrote elsewhere. Check the network panel for the failing URL, then compare it against where the command actually wrote (from git status after a run). If they disagree, the destination is configurable and needs adjusting.

Laravel 13 support in 1.8.1 is a constraint widening, not a compatibility guarantee. It means this package won't block a framework bump. The real gate for a Laravel major upgrade is laravel/nova's own compatibility — check that, not this. Treat the release note as "one less blocker", not "green light".

Keep it in require-dev, permanently. This is a build tool. Shipping it in require drags it into production vendor/ and your runtime dependency surface for zero runtime benefit. Related: with ~21 stars and no dependents, upstream is best-effort. Your protection is structural — one dependency, one command invocation, one revert line.

Don't hand-edit the generated output. If the command produces a file you then tweak, the next run wipes it. Either the output is derived and regenerated (correct for this tool) or you fork the tool. Never both. If you find yourself wanting to edit the bundle, the thing you actually want is to change the source — or drop the bundler for that package.

Debugging checklist when Nova breaks after bundling:

1. git diff — what exactly did the command change?
2. Network panel — any 404 on the bundle URL? (path/publish problem)
3. Console — duplicate Vue, missing component, or $ is not defined? (ordering problem)
4. Temporarily remove the bundle from registration — does Nova recover? If yes, the bundler is the cause; if no, you have a coincidental problem.
5. storage/logs/laravel.log — the command may have printed warnings that scrolled past in the terminal.

Re-measure when your package set changes. The payoff is proportional to how many Nova packages you have installed. If you remove half your tools, the benefit may drop below the maintenance cost of the Composer hook and the CI guard. Keep a one-line note in your dependency register recording the measured before/after (requests and load time) alongside the date — so a future you can decide to drop it on evidence rather than vibes.