Sass Bundle Laravel Package

Getting Started

Read this first: it is not a Laravel package. xrow/sass-bundle is a Symfony bundle. It ships a Bundle subclass, a DependencyInjection extension, and a config tree that Laravel's container will never load. A composer require xrow/sass-bundle in a Laravel app gets you classes on disk and nothing else — no service provider, no auto-discovery, no Blade integration.

So "getting started" splits into two realistic paths.

Path A — you actually have a Symfony app (the intended use case):

1. composer require xrow/sass-bundle
2. Register the bundle in app/AppKernel.php (Symfony 2/3 era) or config/bundles.php
3. Open DependencyInjection/Configuration.php before writing any YAML — that file is the ground truth for config keys, since the README from 2016 is unlikely to match what the code expects.
4. Configure source/output paths, then trigger compilation via the bundle's console command or during cache warmup.
5. Look at the Twig extension next — that's the surface most day-to-day usage goes through (typically a function that emits a <link> to a compiled stylesheet or inlines the CSS).

Path B — you are a Laravel developer (the realistic case): don't install it. You have two genuinely good options:

• Build-time (default, correct choice): Laravel's first-party Vite integration plus the sass npm package. npm i -D sass, point laravel-vite-plugin at your .scss entry, @vite(['resources/scss/app.scss']). You get HMR, source maps, minification, PostCSS/Tailwind, and hashed filenames for free.
• Runtime (rare, but the only scenario where this bundle's idea maps to Laravel): you need to compile Sass inside PHP at request time — e.g. user-editable theme variables stored in the DB. For that, use scssphp/scssphp directly, not this bundle: composer require scssphp/scssphp, then (new Compiler())->compileString($scss)->getCss() behind a cached service.

Your first concrete use case on Path B is almost always the same: compile resources/scss/app.scss into a versioned asset at build time. Vite solves it in ten minutes.

Implementation Patterns

If you are borrowing the idea rather than the package (the only sane way to "use" this in Laravel), wrap a compiler in a service provider:

// app/Providers/SassServiceProvider.php
$this->app->singleton(SassCompiler::class, fn () => new SassCompiler(
    basePath: resource_path('scss'),
    cachePath: storage_path('app/sass'),
));

Then expose it as a Blade directive so templates stay clean:

Blade::directive('sass', fn ($expr) => "<?php echo app(SassCompiler::class)->inline($expr); ?>");

{{-- inline critical CSS for above-the-fold --}}
<style>@sass('critical.scss')</style>

Build-time vs. request-time — pick one per use case. Runtime compilation of a large stylesheet on every request will dominate your TTFB. The pattern that works: compile at build time for the app shell, reserve runtime compilation for a small, bounded set of partials whose inputs are genuinely dynamic, and cache aggressively keyed on a hash of the inputs.

Cache keyed on inputs, not time:

$key = 'sass:' . md5($source . json_encode($variables));
return Cache::rememberForever($key, fn () => $compiler->compile($source, $variables));

Invalidate in your deploy script (or php artisan cache:clear on release), not with a TTL.

Variable injection is the one thing runtime Sass buys you over Vite. Prepend a generated $primary: #ff0000; block to the source string before compiling, rather than string-replacing inside the .scss.

CI/CD: compile in the pipeline (npm step or a php artisan sass:build command you wrote), store output under public/build with a content hash, and let the manifest resolve paths. Commit nothing generated.

If you are on Symfony and stuck with the bundle: treat the Twig extension as the only public API, keep config in config.yml under the bundle's namespace, and make sure the output directory is writable by the web user if it compiles at request time.

Gotchas and Tips

• Abandoned since 2016. Expect PHP 7 syntax, Symfony 2/3 APIs (AppKernel, getContainerExtension), and no PHP 8 / Symfony 6 compatibility. Any modern project will hit fatal errors during container compilation, not at runtime — so a failed composer require is the best outcome you can hope for.
• Zero stars, zero dependents, score 0.06. There is no community to ask, no issue tracker activity, and no security review. Treat the code as untrusted until you've read the exec/shell_exec calls — a Sass bundle of this era may shell out to a sass binary and make path assumptions that are dangerous in a web context.
• No source maps, no HMR, no PostCSS. You are opting out of the entire modern asset pipeline. Tailwind, autoprefixing, and CSS modules are simply not available.
• Debugging order if it silently does nothing: (1) confirm the bundle is registered — a missing bundle registration produces no error, just no output; (2) clear the Symfony cache; (3) verify the output directory exists and is writable, since these bundles typically fail silently on write errors; (4) check whether compilation is gated behind cache warmup, so cache:clear is actually the trigger.
• Config quirks: old config trees use scalarNode/arrayNode builders that reject keys added in later Symfony versions. If your config.yml "looks right" but the container blows up, diff your keys against DependencyInjection/Configuration.php character by character.
• No extension points worth using. No events, no plugin system, no compiler pass hooks of note. If the output format doesn't suit you, fork it — but at that point, port to scssphp instead.
• Migration tip: if you're on Symfony and want out, map the bundle's config keys to a Vite/Encore setup, move the Twig function to a static asset include, and delete the bundle. If you're on Laravel, the equivalent move is Vite — do it on day one rather than retrofitting later.
• The honest recommendation: for a Laravel codebase, the answer to "how do I use this day-to-day" is you don't. Use Vite for build-time and scssphp/scssphp for the narrow runtime case; both are maintained, both have docs that match the code, and neither will cost you a weekend on container errors.