Laravel Assetic Laravel Package

Getting Started

The package is a thin service-provider wrapper around Assetic: you define asset collections in a single config file, expose them in Blade, and compile them with an Artisan command. First contact should be config/assetic.php — everything (collections, filters, debug toggle, output paths) lives there.

Minimal setup (Laravel 5.5+):

composer require barryvdh/laravel-assetic
php artisan vendor:publish --provider="Barryvdh\Assetic\AsseticServiceProvider"

On Laravel 4.x/5.0–5.4 you also register Barryvdh\Assetic\AsseticServiceProvider in config/app.php and alias the facade:

'Assetic' => 'Barryvdh\Assetic\Facade',

First collection — define what a "bundle" is:

// config/assetic.php
'collections' => [
    'app.css' => [
        'public/css/vendor/*.css',
        'public/css/app.css',
    ],
],
'filters' => [
    'app.css' => ['?yui_css'],   // '?' = skip when debug is on
],
'debug' => env('APP_DEBUG', false),

Wire it into a layout — the Blade helper renders the correct tags, expanding to individual files in debug mode and a single combined file otherwise:

{!! Assetic::styles('app.css') !!}
{!! Assetic::scripts('app.js') !!}

Compile once, verify output:

php artisan assetic:dump
ls public/assets/   # confirm the concatenated file exists

First real use case to validate is the full round-trip on one page: define a collection, render it via the helper, run assetic:dump, load the page in debug and in non-debug, and confirm the correct <link>/<script> tags appear in both modes. Do this against APP_ENV=production config:cache before wiring the rest — the debug/prod switch is where most silent breakage lives.

If the package isn't already in the codebase, stop and read the operational notes first; this is a stabilisation tool for legacy Assetic apps, not a greenfield choice.

Implementation Patterns

Collections are the unit of work. Name them by consumer (app.css, admin.js, email.css) rather than by file type. Assetic globs sort lexicographically, so vendor/polyfill ordering is fragile — prefer explicit file lists over *.js globs for JavaScript, where order is load-bearing. Globs are fine for CSS where order usually doesn't matter.

Filters attach per-collection. Built-in names (less, scss, coffee, yui_js, yui_css, cssrewrite, uglifyjs if present) map to Assetic filter classes. The ? prefix makes a filter lazy — skipped while debug is true, applied on dump. Use it for minifiers so development stays readable:

'filters' => [
    'app.css' => ['?less', '?yui_css'],
    'app.js'  => ['?yui_js'],
],

Bind debug to the environment, never hard-code it. The canonical pattern is 'debug' => env('APP_DEBUG', false). Crucially, the runtime value at request time must match the value used during assetic:dump — otherwise Blade emits URLs to files that were never written (or renders un-minified sources in production). Dump in the same environment shape you serve.

Custom filters go in the filters array as fully-qualified class names or Assetic names. If you need project-specific behaviour, implement an Assetic filter class and register it there; the wrapper doesn't have a separate plugin API.

Deploy integration — treat assetic:dump as a build step, not a request-time fallback:

// composer.json
"scripts": {
  "post-install-cmd": ["@php artisan assetic:dump"],
  "post-update-cmd":  ["@php artisan assetic:dump"]
}

Or invoke it explicitly in CI before the release is archived, so the compiled file is baked into the artifact. This is the architectural fork the package pushes you toward: precompiled, immutable assets, not lazy compilation on first hit.

Per-environment behaviour — keep one config file and branch on env vars rather than maintaining separate files. Toggle minification, combine, and output dir via env(). Do not put closures or runtime service bindings in config/assetic.php; config:cache will serialise it and break.

Cache busting is not automatic. Options: append a query string via Assetic::getUrl() if exposed, or include a versioned output filename and reference it from a view composer. Most legacy apps simply set a far-future Cache-Control on the dumped file and rename per deploy.

Gotchas and Tips

Debug flag drift is the #1 failure mode. assetic:dump in debug mode produces individual-file URLs; serving in non-debug expects a combined file. Mismatched values render pages that look fine but reference a 404 (or worse, serve stale files). Always dump and serve under the same APP_DEBUG.

config:cache will bite you. If config/assetic.php uses closures, service resolution, or env() calls the cached config can't resolve, the collections silently misbehave. Test with php artisan config:cache in a production-shaped container before trusting it.

External binaries are runtime dependencies. LESS/Sass/CoffeeScript/YUI filters shell out to lessc, sass, coffee, or java. "Works on my laptop" is meaningless — verify each binary exists in the production image, with a pinned version. Missing binaries surface as generic filter exceptions during dump, not at boot.

Lazy (?) filters only apply on dump. If you skip assetic:dump, lazy filters never run and you ship unminified, unprocessed sources. The dump is not optional.

Filter ordering matters within a collection for preprocessors: less must run before cssrewrite (or URL rewriting will rewrite the wrong asset). The order in the array is the order Assetic applies them.

Stale dump artifacts linger. assetic:dump overwrites known filenames but doesn't clean the output directory. If collections are renamed or removed, orphan files remain and can be served by accident. Add a rm -rf public/assets/* before the dump in CI, or version the output directory per release.

HTML escaping changed across Laravel versions. In 5.x+, the helper returns raw HTML — use {!! Assetic::styles('app.css') !!}, not {{ }}, or you'll see literal <link> tags in the page. In older versions the helper may already escape; check the rendered source on first integration.

No fingerprinting, no source maps, no HMR. The pipeline produces concatenated, optionally minified files. If product needs hashed filenames, source maps per environment, or hot reload, that's out of scope — plan the migration to Vite/Mix rather than trying to bolt it on.

Old filter versions lag modern syntax. A Sass or LESS filter bundled with Assetic-era Assetic may not parse @use, CSS custom property fallbacks, or newer JS syntax in uglifyjs. Verify with a representative file from the actual codebase before assuming the preprocessor works; failing syntax appears only at dump time.

Windows paths. Assetic resolves against the filesystem; spaces and mixed separators in paths break globs. Use forward slashes in config even on Windows, and prefer explicit file lists there.

Pin the package and Assetic versions in composer.json (both direct and as a transitive lock). With no upstream maintenance, a floating constraint is a future unscheduled breakage.

Memory and timeouts. Dumping large collections in one process can hit memory_limit or the CLI timeout. Split into smaller named collections and dump them individually if needed, and raise limits only in the build container — not at request time.