Asset Pipeline

I once spent roughly 3.5 hours trying to figure out why my custom google font and foundation-icons-3 would not render in production on Heroku, and you know what? I learned a lot! Turns out there’s this thing called the asset pipeline, not the kind you’re offered at a rave or the world class Hawaiian reef break, and it determines whether your Rails app is worthy of style when you push it to your production server.

Turns out, the asset pipeline is one of the simplest and least understood rails features for developers. Instead of me just telling you how to make your custom web-font and font-icons work on Heroku, which I will in part-II, I rather compress the brain-drain I just experienced into something of value. Keep in mind this is just a high to mid-level overview, we’ll get into more tricky aspects in part-II.

What is the asset-pipeline?

Your Rails application has a folder called “assets”, assets are just all of your css, javascript, and image files. Think of it as everything that’s going to turn your plain ol HTML page into a stylish, interactive beauty. The asset pipeline serves 3 very important purposed: precompiling higher level languages, concatenating assets, and minifying files.


The only native language to most browsers is JavaScript, but browsers also have HTML and CSS parsers. These are lower level languages for the browser. Your stylesheets written in Sass and scripts written in CoffeeScript have to be pre-compiled(translated) into these lower level languages for the browser to properly render your pages.



Any file you create inside the assets folder essentially becomes part of the asset-pipeline, but you should stick to convention and add CSS files to the stylesheets folder and JS files to the javascripts folder. There’s 2 dominant files you need to pay attention to: application.js and application.css. These files are called Manifests, no relationship and not nearly as destructive as the Manifest Destiny. Essentially each of these files pull in(concatenate) all other files with like extensions. It’s actually the Sprockets Gem that’s doing this magic. For example, if you have 5 custom CSS files inside of Assets, the application.css is going to pull in all of those files and create one big file. How? The require_tree . directive, inside the Manifests is a command that says “get over here all you like files.” The require_self directive just says: “every bit of code inside this Manifest file is gonna join the party as well.” Why? Because concatenating things into one file for the server to hand to the client(browser) improves Performance! In the JS Manifest the directives begin with //= and in CSS with *= , they essentially do the same thing.



Lastly, the asset-pipeline is responsible for minifying these Manifest files. Think of how much extra space and comments each one of your stylesheets and JavaScript files contain, and picture removing all of that, that’s what a minified file looks like. Long variable names are also chopped down. The functionality ends up unchanged, the code is just smooshed together like that house party I was at last week. Why minify? Performance!


Awesome, but how does your application actually find these Manifest files? Magic! Along with link_tags inside your application layout: app/views/layouts/application.html.erb. Consider this file a universal default master file for all the views. It’s sorta like a Manifest file in the sense that it pulls all of the HTML from each one of your view files into itself by way of <%= yield %> (if you’re using erb as your templating language). We link stylesheets and scripts in the <head> of this file like this: <%= stylesheet_link_tag “application” %>. This points to the Manifest CSS file.

Sometimes just the order in which you require files might be incorrect, which causes certain files to override others. This is quite possibly the most important and overlooked section in Rails docs:

Directives are processed top to bottom, but the order in which files are included by require_tree is unspecified. You should not rely on any particular order among those. If you need to ensure some particular JavaScript ends up above some other in the concatenated file, require the prerequisite file first in the manifest. Note that the family of require directives prevents files from being included twice in the output.


In conclusion, you’re application layout file has a link pointing to your Manifest files. These Manifests should already be requiring all of your assets in the order in which you intend. Roughly 90% of problems I’ve seen people have with the asset pipeline come from improperly requiring files or frameworks from within their Manifests.

Leave a Reply