Deploy Bundle Laravel Package

Getting Started

1. Require the package with Composer and let the service provider auto-register (or add it to config/app.php on older Laravel versions).
2. Publish the config file (php artisan vendor:publish) — this is the first place to look. It holds the npm binary path, default working directory, and (as of 0.8.0) the Webpack build settings.
3. Confirm the toolchain is visible to PHP: which npm and which node from the same user that runs php artisan and, more importantly, the same user that runs PHP-FPM/queue workers.
4. First use case: replace a hand-rolled exec('npm run build') in a deploy script with the package's build call, pointing it at your assets directory rather than the project root.

Start with a single directory (your app root) before wiring up multiple frontends. The 0.8.0 "npm in any dir" capability is the headline feature; prove it works on one path first, then expand.

Implementation Patterns

Deployment hook. Wrap the package's install/build calls in an artisan command of your own and call it from your deploy pipeline (Envoyer, Deployer, GitHub Actions). Keeping the invocation behind your own command means the package's API changes only touch one file.

Multiple frontends, one Laravel app. With npm execution in arbitrary directories you can keep resources/assets, a separate packages/admin-ui, and a legacy public/theme each with their own package.json, and build them from a single artisan command. Define these paths in config rather than hardcoding them in the command so they can differ per environment.

Webpack config generation. For the Webpack path, generate the config from Laravel-side values (entry points, output paths, public path, env-derived NODE_ENV) rather than maintaining a static webpack.config.js. This keeps asset URLs consistent with APP_URL and avoids the classic mismatch where compiled files land somewhere the mix()/asset() helper doesn't expect.

CI vs. local split. Use the package for local convenience builds, but in CI prefer an explicit npm ci step before invoking the build so lockfile enforcement isn't silently bypassed by whatever install semantics the package defaults to.

Fail loudly. Wrap build invocations in a check on the exit code and surface stdout/stderr in the exception message. A silent non-zero exit that still produces a stale public/js is the most common way this class of package burns an afternoon.

Gotchas and Tips

• PATH is per-process. npm working from your terminal says nothing about the PHP-FPM or queue-worker environment. Pin an absolute path to the npm binary in config for anything non-interactive.
• Working directory semantics. "Any dir" usually means the package chdirs or passes a --prefix. Know which, because --prefix and a real chdir differ for scripts that resolve paths relative to process.cwd(). Verify a build from a nested directory actually emits files where you expect.
• Relative paths resolve against the process, not the config file. Prefer absolute paths derived from base_path() in your config.
• 0.x versioning. This is a pre-1.0 package; treat minor bumps as potentially breaking. Pin the version in composer.json and read the diff before upgrading — 0.8.0's two bullet points are terse enough that the changelog alone won't tell you what changed in the invocation API.
• Node/npm version drift. Local Node 22 and CI Node 18 will produce different Webpack output and different lockfile behaviour. Assert the Node version in your build command.
• Artifact staleness. If you cache public/ or node_modules between deploys, a failed build can leave old assets in place with a green deploy. Delete-then-build, or checksum the output.
• Permissions. Builds run as www-data vs forge vs root leave node_modules and public/build owned by the wrong user, which surfaces later as a confusing 403 rather than a build error.
• Extension points to check first: the npm binary path and default working directory in config, any published Webpack template you can override, and whether the package fires events around build start/finish — hooking those is cleaner than wrapping the calls yourself if they exist.
• Debugging: when a build fails with no useful output, run the exact same command manually from the exact same directory as the same user. If it succeeds there, the problem is environment (PATH, permissions, env vars), not the package.