23 Nov 2011

The Rails 3 asset pipeline in (about) 5 minutes

By tagged as , , , , .
On 23 Nov 2011

Even though the asset pipeline was announced a few months ago and has been available in Rails 3.1 for a while now, it’s taken me some time to getting  to complete understanding what it’s all about. I’ve tried to condense what I’ve learned here in a post that you can hopefully digest in 5 minutes or so.

The basics

As David Heinemeier Hansson said at Railsconf 2011, the asset pipeline has one main goal, that is to make it easy to treat assets such as js code and css as first class citizens in your Rails app. Practically it does so using 3 things, asset directories, manifest files and engines.

Asset directories

In Rails 3.1 your assets can live in one of three (default) directories

  • app/assets for assets that are closely coupled with your application
  • lib/assets  are for your own custom libraries that can be shared across applications
  • vendor/assets are for third party assets used by your application

Once in these directories, the pipeline will be aware of your assets, and can now do a number of helpful things. First off, Rails will help you organise and  manage dependencies between your assets, using manifest files.  Next, it can run a number of preprocessors using engines, letting you use things like Coffeescript and Sass. Finally it will give you all of the minification, file concatenation and caching fingerprint goodness for your production environment.

Manifest files

These are plain js or css files containing directive processors, comment lines followed by a =
// ...
//= require jquery
//= require jquery_ujs
//= require_tree .

Or:

/* ...
*= require_self
*= require_tree .

These manifest files reference and include other assets that they depend on. require_directory and require_tree lets you require whole directories and their children, require_self also includes any js or css in the manifest file itself.

The real magic is the ability to require other manifest files, which then lets you easily organise your code and build a dependency tree. Getting to your assets in your views is as easy as it always was, you still use the familiar javascript_include_tag and stylesheet_link_tag as well as image_tag. It will all work fine, even when Rails does file fingerprinting in production.

Preprocessing engines

The pipeline comes with a few preprocessors that will run whenever a file is requested. It knows what processor to run by looking at the file extension. For example, when a file posts.js.coffee is requested, the pipeline will first run the coffescript compiler and return a js file with the output. .scss files will be processed by Sass. You can easily run multiple processors on the same file by adding extensions to the file name.
These are run from right to left, for example styles.css.scss.erb will first run the file through erb and then Sass.

Done already?

Yep, that’s basically the least amount I can say about the asset pipeline without being useless. Of course I have left out a ton of stuff, but luckily there are some excellent resources out there to fill you in on the details:

Rails Edge Guide

Rails 3.1 Asset Pipeline in the Real World

dhh on the Asset Pipeline at Railsconf 2011

 

Update

I’m very honored that Michael Hartl based the structure of his section on the asset pipeline on this post in his most excellent Ruby on Rails tutorial. I would highly recommend this tutorial as the best way to learn Rails.

 

    Michael Erasmus

    Michael has been developing software for over 9 years. He has been a C# programmer for quite a few of them, but has luckily been enlightened enough to become a open source zealot the last few years. The most loved tools in his utility belt are Ruby and Rails, Linux, MongoDB, Vim, jQuery and Coffeescript. He's interested in all manner of science and technology, but tends to dwell on things like elegant and eccentric programming languages, machine learning and statistics, web development, internet startups and civic hacking. When he's not sitting in front of the computer he likes pulling faces to amuse his baby son, apologising to his wonderful wife for sitting in front of computer all day or arguing endlessly with friends, family, colleagues and random strangers. He lives next to the beach in Muizenberg, Cape Town and loves it.

    Michael Erasmus has written 11 articles.

    3 Responses to “The Rails 3 asset pipeline in (about) 5 minutes”

    1. Last Week’s Top Ruby News: Rails 3.1.3, autoload deprecated, and conferences says:
      November 29, 2011 at 12:02 am

      [...] The Rails 3 Asset Pipeline in (about) 5 Minutes Michael Erasmus was feeling unsure about how the asset pipeline in Rails 3.1 worked but after digging around for a while, he's put together a simple high level overview. [...]

      Reply
    2. Alvaro says:
      January 13, 2013 at 2:00 pm

      Great article, Michael. Thanks for it.

      By the way, I’m having trouble getting pipeline to work in the way you’ve mentioned. With ERB sending to SASS, which sends to the final CSS.

      Testing a code like this:
      .my-class { width: [ERB open tag] “10px” [ERB close tag] }

      Will throw an error like this:
      Invalid CSS after “…class { width: “: expected expression (e.g. 1px, bold), was “[ERB open tag] “10px” [ERB close tag] }”

      Using Rails 3.2.9, sass-rails 3.2.5.

      Are you sure SASS can really be used with ERB?

      PS.: [ERB open tag] and [ERB close tag] were used so as to avoid final text from being clipped off.

      Reply
      • michael says:
        January 13, 2013 at 5:53 pm

        To be quite honest, I’ve never tried doing that in SASS file, however I’m pretty sure it works with CoffeeScript.

        Reply

    Leave a Reply