Updated February 3, 2012: Literally days after this article was originally posted, the Compass and Rails landscape changed yet again with the introduction of the
compass-rails gem. We’ve revised the instructions below to use the very latest technique.
If you need some background on Compass, refer to our earlier post: Compass Will Change Your Life.
Where is the official Compass documentation?
Official documentation for installing Compass in a Rails 3.1 or 3.2 application can be hard to find. In fact, the instructions on the official Compass site are way out of date.
Luckily the owner of the Compass project posted a Gist on GitHub last September with some tips for installing Compass in Rails 3.1. But as of February 2012 even those instructions have become out of date. Now your best bet is to use the new compass-rails project README on GitHub.
How we install Compass in a new Rails 3.1/3.2 project
We’re documenting in this article the Compass/Rails installation steps that have worked for us. These have been tested in development and production with real apps.
1. Add compass-rails to the Gemfile
compass-rails gem is the critical “glue” that connects Compass to the Rails asset pipeline. This gem should be placed in the
:assets group of your Gemfile. You should not include the
compass gem explicitly; you’ll get it automatically via compass-rails. If you use any Compass plugins, like sassy-buttons, add them here too. Run
bundle install when you’re done.
2. Delete application.css and replace with application.scss
The asset pipeline relies heavily on file extensions to work its magic, so it is important to use the name
application.scss: the scss extension tells Rails you want to use Compass. Also note that
.scss files differ in how they import other stylesheets. In scss files, always use @import. Here’s how your
application.scss file should look:
3. Create compass.rb (optional)
The default configuration of Compass will work nicely with Rails. If you want to tweak Compass settings, you’ll need to create a
config/compass.rb file in your Rails app. It’s probably a good idea to create this file, even if it is empty, so other developers (and your future self) know where Compass configuration is supposed to go.
Here at 55 Minutes, there is one important setting that we always use with Compass. We use our css3-foundation project, which organizes scss files into subdirectories. Compass won’t allow us to load partial scss files from these directories unless we explicitly add them to the Compass load path. So our configuration looks like this:
Now we can write
@import "grid" and Compass will successfully find the file
4. Use image-url
The Rails asset pipeline will do some fancy stuff like automatically add cache-busters to all of your images (e.g.
logo-small-fd1a40e11357a70159b4342f33ee30e2.png). During development you can’t predict what those cache-busters will be, so how do you reference images in your stylesheets?
The answer is to use the
image-url helper. Always use
image-url() instead of plain CSS
url() in your stylesheets. For example:
5. Follow the standard asset pipeline file organization
Per the asset pipeline guide, your scripts, stylesheets and images should all be placed in the
app/assets/ directory. This applies to stylesheets written in scss as well. The directory structure should look like this:
That should do it. You’re ready to use Compass to develop your app!
But wait, there’s more: deploying to production
A full explanation of Rails deployment is beyond the scope of this article, but there is an important step that relates specifically to Compass and the asset pipeline.
When deploying your app, run
bundle exec rake assets:precompile on the Rails app server before you start it up. By default, Rails will not serve stylesheets, scripts or images in production, so these need to be assembled ahead of time. Running the
assets:precompile task tells Compass to compile the scss; Rails will also add cache-busters, apply compression, and stage everything into the
public/assets directory. Your web server (Nginx, Passenger) will then do the heavy-lifting of serving those out to clients.
Precompilation is tricky, though. One thing that can go wrong is stylesheets other than
application.scss will not get precompiled at all. For example, let’s say you have a special
1024.scss file for serving to desktop browsers. By default, that file will not get compiled, leading to catastrophic errors at runtime. You might see:
Or, if you followed older recommendations for Compass and Rails integration, you might find that the
rake assets:precompile task fails with a rather obtuse error. For example, you might see this:
To fix these problems and finish your Compass installation, you’ll need to take one more step.
6. Specify config.assets.precompile in application.rb
We need to explicitly tell Rails which scss files to compile, using the
config.assets.precompile setting. We can either list each scss file individually (a maintenance headache for large projects), or we can provide a regular expression to match them all.
Be careful with the regular expression, though: if the expression is so broad that it captures partial scss files (i.e those that start with an underscore), Rails will try to compile those files individually, leading to errors. For example, in the error message above, we mistakenly told Rails to precompile
_grid.scss, where it blew up.
The solution is to tell Rails to ignore files that begin with the underscore character when running the precompile task, but include everything else. Chris Eppstein’s original Gist suggested a regular expression for this purpose but it was incomplete: his regex ignored underscore files at the root level of the assets directory, but it failed to ignore underscore files in subdirectories (like our
Here’s a more bulletproof regex. Place this in
rake assets:precompile will do the right thing. You’re all done!
Send us your feedback by commenting on the Gist for this post on GitHub.comments powered by Disqus