Assets Laravel Package

Getting Started

Install

composer require stolz/assets

Laravel wiring

On Laravel 5.5+ the service provider is auto-discovered. On older versions add it manually in config/app.php:

'providers' => [
    Stolz\Assets\Laravel\ServiceProvider::class,
],
'aliases' => [
    'Assets' => Stolz\Assets\Laravel\Facade::class,
],

Publish the config and trim it to what you actually use:

php artisan vendor:publish --provider="Stolz\Assets\Laravel\ServiceProvider"

// config/assets.php (essentials)
return [
    'public_dir' => public_path(),
    'css_dir'    => 'css',
    'js_dir'     => 'js',
    'engine'     => 'Laravel',
    'minify'     => env('ASSETS_MINIFY', false),
];

First use case — replace a pile of hand-written <link>/<script> tags in layouts/app.blade.php:

<head>
    {!! Assets::add('vendor.css')->add('app.css')->css() !!}
</head>
<body>
    ...
    {!! Assets::add('app.js')->js() !!}
</body>

That single change gives you ordered output, optional concatenation/minification, and one place to add per-page assets.

Where to look first

1. README.md — the API is small; the examples are the real documentation.
2. config/assets.php — directory mapping, collections, minify/pipeline switches.
3. src/Manager.php — the fluent add()/css()/js()/render() surface and how groups are stored.
4. src/Laravel/ServiceProvider.php + facade — what is bound as a singleton (this matters later).
5. tests/ — the fastest way to see edge-case behavior for missing files and groups.

Implementation Patterns

Layout renders, views register. Because Blade executes the child view before the layout, a page view can call Assets::add('js/charts.js') and the layout’s Assets::js() will still pick it up. Use this instead of @push/@stack if you want a single asset pipeline for the whole app.

{{-- resources/views/reports/show.blade.php --}}
@php Assets::add('vendor/chart.js')->add('js/reports.js'); @endphp

Groups for <head> vs. end-of-body. Keep CSS and JS in separate buckets so you don’t have to split the layout manually:

Assets::group('head')->add('app.css');
Assets::group('body')->add('app.js');

{!! Assets::render('head') !!}
...
{!! Assets::render('body') !!}

Collections for vendor bundles. Define repeatable bundles once in config, then add them by name in views. This is the cleanest way to bump jQuery/Bootstrap versions in one place.

'collections' => [
    'vendor' => ['jquery.min.js', 'bootstrap.min.js'],
    'vendor-css' => ['bootstrap.min.css'],
],

Environment-aware minification. Enable minify only in production; keep it off locally so you can debug unminified output. Prefer a dedicated env var so you can toggle it without a deploy:

'minify' => env('ASSETS_MINIFY', app()->environment('production')),

Version your URLs. This package predates content-hashed filenames. Append a cache-buster yourself (from filemtime() or a deploy tag) when generating tags, otherwise browsers will happily cache CSS/JS across releases.

Keep it isolated from Vite/Mix. Don’t let two asset systems write into the same layout. If the project uses Vite, use this package only for legacy pages served outside the Vite entry points, and keep the two code paths clearly separated in the layout.

Testing. In feature tests, assert against rendered HTML (assertSee('css/app.css')). Because the manager is typically a container singleton, remember to reset it between requests.

Gotchas and Tips

• Escape output correctly. css()/js()/render() return HTML, so they must be echoed with {!! !!}. Using {{ }} produces visible escaped tags — the most common first-day mistake.
• Silent failures on bad paths. A wrong css_dir/js_dir or a filename typo usually yields a perfectly valid <link> to a 404, not an exception. Add a smoke test that asserts every registered asset exists under public_dir.
• No dependency resolution. Assets render in insertion order; there is no graph. If app.js needs jQuery, add jQuery first explicitly (or bundle both in a collection) — the package will not infer it.
• Singleton state leaks. The manager accumulates add() calls. In PHPUnit this can bleed between tests; under Laravel Octane it can bleed between requests. Flush/reset the instance in tearDown() or on each request boundary.
• Path vs. URL assumptions. Generated URLs assume the app is served from the domain root. Behind a proxy, a subdirectory deploy, or a misconfigured APP_URL, the links will be wrong even though the files exist. Verify with curl against the generated URL, not just the filesystem path.
• Minification cache staleness. If minify/pipeline mode writes combined files to a cache directory, stale or half-written files survive deploys. Clear that directory as part of your release step and make sure it is writable by the web user.
• Pipeline mode needs a route. If you enable on-the-fly combining, confirm the route is registered and not caught by a catch-all route or a WAF/CDN rule before you debug the PHP side.
• No ES modules, no HMR, no tree-shaking. The library concatenates and minifies plain CSS/JS. It does not understand import, .mjs, TypeScript, or PostCSS. For any modern frontend, keep Vite/Mix; use this only for plain assets.
• Maintenance risk. Last release was early 2020. Expect PHP 8.x deprecation notices from dependencies and no fixes for newer framework versions. Pin the version, and be prepared to fork or replace it if the project has a long lifespan.
• Extension points. Config drives collections, groups, and directory mapping; subclassing the manager lets you override URL generation or tag rendering; you can rebind your own instance in the container if you need custom behavior.
• Debugging checklist. Dump the raw render() output, confirm the exact <link>/<script> attributes, check the file exists at public_dir/css_dir/..., then check the served URL returns 200. That sequence isolates almost every failure quickly.