Compass Bundle Laravel Package

Getting Started

This is not a Laravel package. rodgermd/compass-bundle is a Symfony2-era bundle that wraps the Ruby Compass framework (which compiles .scss/.sass to .css). If you arrived here from a Laravel package search, the closest Laravel equivalents are Laravel Mix or Vite — this bundle will not install or boot in a Laravel app without significant adaptation.

If you're maintaining a legacy Symfony codebase where it's already present:

1. Confirm prerequisites before anything else. You need a Ruby interpreter, the compass gem (gem install compass), and Ruby Sass on PATH. Compass and Ruby Sass are both end-of-life upstream, so verify versions resolve on the target machine.
2. Register the bundle in app/AppKernel.php (Symfony 2 style) or config/bundles.php if a fork has been updated — check the repo README first, the Symfony2 registration path is the documented one.
3. Locate the config root in app/config/config.yml. The bundle exposes a compiler/asset configuration node that defines source directories (where .scss lives) and target directories (where .css is emitted). This is the first place to look.
4. First meaningful use case: point the source dir at your Resources/public/sass folder, target at the corresponding web/css output, and run the bundle's console command to compile once. Verify CSS lands on disk before wiring it into Twig or Assetic.

Reality check: with 2 stars and 0 dependents, expect to read the source directly rather than rely on docs. Budget time for spelunking.

Implementation Patterns

• Config-driven compile step, not runtime asset serving. Typical workflow: define source/target dirs in config.yml, run the compile console command locally after editing SCSS, and commit or deploy the emitted CSS. Treat it like a build artifact, not a request-time filter.
• Pair with Assetic for production. In Symfony2 projects of this vintage, CompassBundle is meant to feed .css into Assetic's dump/assetic:dump pipeline. The bundle is one stage; Assetic is the assembly line.
• Deployment hook. Add the compile command to your deploy script (Capistrano, Deployer, or a CI step) before assetic:dump. Never assume compiled CSS is fresh in a release.
• Dev loop: keep a Compass watch process (compass watch <dir>) running outside the bundle for live recompilation — the bundle's compile command is one-shot. The bundle handles release builds; the Ruby CLI handles the edit-refresh loop.
• In a Laravel-adjacent world, this pattern maps to mix.sass() / vite with a npm run build step. If you're modernizing, port the SCSS sources straight into Vite and drop the bundle entirely — there's nothing Compass-specific you can't express with sass + autoprefixer.

Gotchas and Tips

• Abandonment is the biggest gotcha. Compass and Ruby Sass reached end-of-life years ago; this bundle hasn't kept pace. Any "how do I leverage it day-to-day" answer is really "maintain it if it's already in place, otherwise don't adopt it."
• No Laravel entry point. There's no service provider, no facade, no config/compass.php. Don't expect php artisan commands — this is Symfony console plumbing.
• Debugging silent failures is almost always environment, not code: check which ruby, gem list | grep compass, the exact binary path the bundle shells out to, and filesystem permissions on the output directory. The compiler runs as a subprocess, so PHP errors won't surface — capture stderr from the Ruby call.
• Config node naming varies across forks. Read the bundle's DependencyInjection/Configuration.php (or equivalent) to find the real config root and accepted keys — don't trust examples in blog posts, they drift between Symfony minor versions.
• Extension points are limited: custom load paths and import directories via config are the main levers. Adding Compass plugins means editing the generated config.rb or gem environment, which tends to break on upgrades.
• Escape hatch: if you're stuck on it, invoke compass compile directly from a Composer script or Makefile and skip the bundle. You lose the Symfony integration and gain a debuggable, documented CLI.
• Migration advice: sass (Dart Sass) + sass-loader/Vite supersedes everything here. For an active Laravel project, use Vite's laravel-vite-plugin; for a Symfony project, use Webpack Encore. Only engage this bundle when a legacy project pins you to it.