Untangling the Rails Asset Pipeline, Part 1

The asset pipeline feature introduced in Rails 3.1 is deceptively simple on the surface. As with many aspects of Rails, if you use the asset pipeline in the “Rails way” you’ll have no problems. But deviate even slightly from the defaults and you may end up thoroughly confused. In the first article of a four-part series, I’ll talk about how caching and Compass relate to the asset pipeline.

The Rails asset pipeline, among other things, optimizes delivery of stylesheets and JavaScripts to the browser, automatically supports Sass and CoffeeScript, and imposes a new project structure. If you aren’t yet familiar with the Rails asset pipeline, read the excellent Rails guide on the subject.

What follows in this series of articles are tips, gotchas and alternative explanations for what might not be clear in the official documentation.

Caching and the asset pipeline

As web developers we know that the browser cache can be trouble. When a fellow developer encounters an inexplicable visual glitch, our first reaction is “did you try clearing your browser cache?”

Safari on the Mac is particularly stubborn: sometimes “empty cache” (⌥⌘E) is not enough, and you’ll need to quit and relaunch as well. If you are wrestling with favicons, a more drastic measure is needed: choose Safari→Reset Safari to clear that particular cache. And of course you’ll want to restart Safari again for good measure.

The good news is that with the introduction of the asset pipeline, Rails has taken big strides to address browser caching problems. If you’ve glanced at the asset pipeline guide you probably know that Rails sends must-revalidate headers in development and uses cache busters in production. Browser caching solved, right?

The bad news is that in development, Rails adds a new asset cache to the mix. This cache speeds development–without it your app would be nearly unusable–but as a result, mysterious glitches can pop up that are only solved by clearing the cache. As with the browser, it is a helpful to know how to clear this cache too.

To wipe out the asset pipeline cache, a brute force rm -rf tmp/* will suffice. This has certainly fixed a few otherwise inexplicable CSS and JavaScript glitches in my experience. As a preventative measure, it might also be a good idea to clear the cache after upgrading gems or changing the asset pipeline configuration, although this may just be superstition.

Finally, if you are experimenting with rake assets:precompile in your development environment (more on this in a later article), you’ll also want to rm -rf public/assets/* afterwards to clean that up.

What about Compass?

As of this writing, Compass project is undergoing major changes at it approaches its 0.12 release. As a result, the recommendations for integrating Compass with Rails are in flux. The latest and greatest technique involves the new compass-rails gem.

Before integrating Compass, seriously consider whether you actually need it. The asset pipeline provides a build system that does a lot of what Compass has traditionally done, and there are other gems like bourbon and autoprefixer-rails that are leaner alternatives to Compass’s CSS3 mixins.

Continue reading part 2 of this series: Production.