Asset Bundle Laravel Package

Getting Started

Before you type composer require. This package has 0 stars, 0 dependents, and no public issue corpus, so there is no "getting started" guide beyond the README. Your first 60–90 minutes are source-reading, not installation. Open these files in order:

1. composer.json — confirm the illuminate/* and php constraints actually include your Laravel version. Do not assume; the README's compatibility claim is not a contract.
2. src/*ServiceProvider.php — find what it registers (Blade directives, singletons, console commands) and whether it writes to disk at boot.
3. The published config file — this is the whole mental model of the package; bundles are defined here.
4. The minify/compile class — check whether it shells out to node/terser or uses a pure-PHP minifier. That single fact determines your CI and container requirements.

Install pinned, not floating:

composer require integrated/asset-bundle --dev   # start dev-only
# then pin to the resolved SHA in composer.json before it touches main

Publish the config (verify the tag name from the provider's publishes() call — it may be asset-bundle-config, config, or absent entirely):

php artisan vendor:publish --provider="Integrated\AssetBundle\AssetBundleServiceProvider"

First use case — the one worth validating: define a single app bundle containing your layout's CSS and JS, reference it from resources/views/layouts/app.blade.php with the package's directive, then run the same page under APP_ENV=local and APP_ENV=production with php artisan config:cache applied. If those two environments disagree about the asset URL, stop and reconsider — that is the exact failure mode this class of package produces in production, and you want to find it in an afternoon on a branch, not on deploy day.

The directive and helper names (@assetBundle, @bundle, asset_bundle() — whatever they are) must be read from the provider. Guessing wastes more time than reading.

Implementation Patterns

Config-first bundling, one file per concern. The package's value is a single declarative map of bundle name → source files → output path. Keep that map honest: one bundle for the global layout, one per page or per feature area, and nothing that isn't referenced by a view. The expected shape is roughly:

// config/asset-bundle.php (verify keys against the published file)
'bundles' => [
    'app'    => ['js' => ['resources/js/app.js'],  'css' => ['resources/css/app.css']],
    'admin'  => ['js' => ['resources/js/admin.js'], 'css' => ['resources/css/admin.css']],
],
'output_path' => 'assets/build',   // verify
'minify'      => env('ASSET_MINIFY', true),

Build once in the pipeline (php artisan asset-bundle:build, or whatever the registered command is), commit nothing, and cache the output directory in CI between runs.

Environment-aware inclusion, not environment-aware config. Rather than branching in Blade (@if(app()->isProduction())), let the package decide. In local it should emit individual unminified files for readable stack traces; in production it emits the hashed bundle. Your layout template stays identical across environments — that is the whole point and the only thing keeping the two paths from drifting.

Stack-based composition for page-specific bundles. Push bundle names onto a Blade stack from child views and render the stack in the layout. This keeps per-page asset loading declarative and prevents the "which view includes which script" archaeology that hand-rolled <script> tags always produce:

{{-- layouts/app.blade.php --}}
@assetBundle('app')
@stack('assets')

{{-- pages/reports.blade.php --}}
@push('assets') @assetBundle('reports') @endpush

Treat it as a post-processor, not a replacement for your source build. The realistic integration for a modern Laravel app is: Vite (or Mix) compiles source → this package concatenates/minifies/hashes the already-built artifacts in public/. Two build steps, one direction of flow. Do not wire it to consume raw resources/ files if you're also running Vite — you will have two answers to "what is the URL for app.css" and they will diverge the first time someone adds a plugin.

Parallel-run behind a flag for evaluation. If you're spiking this against an incumbent, add an env flag that switches the layout between @vite(...) and the package's directive, both pointing at equivalent output. Compare: hashed filename stability across two consecutive builds, response headers, and the resulting bundle sizes. One sprint, then decide.

Deploy sequence that actually works:

composer install --no-dev
npm ci && npm run build        # source compilation
php artisan asset-bundle:build  # bundling/minify/hash
php artisan config:cache
php artisan route:cache
php artisan view:cache

Run this exact sequence in CI, not just php artisan test. Config-cache interaction is where service-provider-registered asset paths classically break, and a green test suite says nothing about it.

Write your own smoke test regardless. Two assertions, both cheap, both catching the expensive failures:

// 1. the URL your layout actually renders returns 200
// 2. two consecutive builds produce identical hashed filenames

The second one protects CDN cache hit rates and is trivially overlooked.

Gotchas and Tips

• You are the QA team. Zero dependents means no Stack Overflow answers, no blog posts, no one else's production incidents to learn from. Every behavior you rely on, you must verify and then document in your own runbook — assume the README is aspirational rather than descriptive.
• Runtime writes to public/ are a blocker, not an inconvenience. If the package compiles on request rather than only via an artisan command, it will fail in a hardened, read-only container. Confirm build-time-only before you go further; if it isn't, the evaluation is over.
• config:cache is the highest-probability breakage point. Service providers that resolve asset paths at boot can bake absolute paths into the cached config, producing production-only 404s. Test the full deploy sequence, not artisan serve.
• Verify hash determinism explicitly. Content-hashed filenames that change on every build will silently destroy your CDN hit rate while looking perfectly fine in the browser. Build twice in CI and diff the output directory.
• Never mix asset() with bundled paths. If a hashed filename is in play, asset('assets/app.css') resolves to the unhashed or stale path. Every reference must go through the package's directive or helper. Grep the codebase for hardcoded public/assets strings before you flip the switch.
• Watch for Blade directive collisions. A directive named @asset will shadow or be shadowed by framework/other-package directives, and the failure is a silently unrendered asset or a PHP parse error inside a compiled view. Clear storage/framework/views after install and check php artisan view:cache passes.
• Ordering against Vite matters. If Vite's manifest and this package's manifest both exist, whichever the template asks for wins — and it will be inconsistent across views over time. Pick one source of truth per asset class and document it in the repo, not in someone's head.
• No HMR, no SSR, no plugin ecosystem. Developer experience here is strictly worse than Vite's for anything beyond "concatenate and hash these files." Do not attempt to make it carry a module graph.
• Extension points are your insurance. While reading the source, note whether the minifier and the hashing strategy are swappable via container bindings or config. If they're hardcoded, then any future need (different hasher, SRI attributes, CSP nonces) means patching a vendored copy — factor that into the go/no-go.
• Debugging a missing asset: dump the resolved config (config('asset-bundle')), confirm the output directory exists and is readable by the web user, confirm the build command actually ran in that deploy, then log the final resolved path from the directive. In that order — path resolution, not minification, is almost always the culprit.
• Exit plan, written down before adoption. The removal cost should be: delete the Composer entry, remove the provider from bootstrap/providers.php, replace N directives in layouts with @vite. Count N. If N is large and scattered, that number is your real lock-in, and it's the number the decision should weigh.