Words and Code

One writer’s journey from words to code.

The Asset WHUTline?: Revisiting the Asset Pipeline After JavaScript

Two weeks ago, I was introduced to the Asset Pipeline. I didn’t really think much of it at first, and part of me even assumed that I’d never really have to see it again. It was a little like going out on a pretty forgettable first date – nothing particularly intriguing about the whole thing, but it somehow leaves you feeling kind of confused and generally rather perplexed.

But here’s the thing: I did see the Asset Pipeline again. And boy was it awkward. After learning JavaScript this week and brushing up on my Rails, I realized that I’m going to run into the Asset Pipeline at some point or another, so I might as well get to know it a little better. Here’s a little refresher just in case you haven’t seen the Asset Pipeline in awhile, either.

Why bother?

Once upon a time, before Rails 3.0, anytime you wanted to include a JavaScript or CSS file in your application, you had to manually do it by including either a <script> or a <link> tag, like so:

<script src="jquery.js" type="text/javascript"></script>
<link href="custom.css" rel="stylesheet" type="text/css"/>

Imagine doing that for every single file in your application. Are you in pain yet? Yeah, me too.

Now imagine being able to create as many JavaScript and CSS files as your heart desired, and being able to include all of them together in one single, long concatenated file that would be delivered whenver the browser makes a page request.

Guess what? That’s exactly what the Asset Pipeline does. Ultimately, the goal of the Asset Pipeline is to make your life as a programmer that much easier by helping you organize your JavaScript and CSS files (which, let’s face it, you are going to have to use):

“I think empty folder and empty files are two of the pivotal innovations in Rails that has encouraged us to write clean applications since the framework appeared. And I think this is true because when you have a place for everything and everything is in it’s place, things feel nice.”

– David Heinemeier Hansson, RailsConf 2011

Explain me some pipeline

The Asset Pipeline works directly with your JavaScript and CSS files (also known as assets), and functions within three main directories:

  1. The app/assets directory: for files that are owned by the application & specific to the current project (such as custom images, JavaScript files or stylesheets).
  2. The lib/assets directory: for assets for your own libraries’ code.
  3. The vendor/assets directory: for external libraries that are owned by someone else (for example, JavaScript plugins or CSS frameworks).

Within your assets directory are two subdirectories: app/assets/javascripts/ and app/assets/stylesheets/. The Asset Pipeline compiles any JavaScript and CSS files that you add to these folders and automatically adds them to every page of your application.

Within these folders are manifests, which, in the case of your CSS files, would be included as part of the default application layout in the app/assets/stylesheets/application.css.scss directory. A manifest sets directives to provide the exact order and list of files that should be concatenated and included in the single CSS file that is delivered to the browser.

So…what exactly is a directive, again?

Directives are nothing more than directions of which files to grab and glob together. In the comments at the top of any manifest, you can find something that looks like *= require_tree, which is a directory that includes the current directory plus its subdirectories.

The most basic directive is require, which will concatenate the content of the specified file only once into the final packaged asset (called the “bundle”).

Another common directive is include, which is similar to require, except that if it reads the same file more than once, it will insert it into the bundle again.

Other directives like require_self and require_directory are useful in grabbing the current file (such as the manifest file), a specified directory.

Directives are always are processed in the order that they are read in the file, with require_tree being the one exception to this rule.

Help me help you (or just use a helper method)

The Asset Pipeline has helper methods to make your life a little easier. Two of the most common helper methods are the stylesheet_link_tag and javascript_include_tag, which can be used to add CSS & JavaScript to any page of your application.

Another useful method is link_to, which can replace the anchor <a> tags while linking to other parts of your application. This method takes two parameters: the string displayed as the anchor text for the link, and the route:

<ul class="nav">
  <li><%= link_to 'Super Cute Kittens', kittens_path %></li>
  <%= render 'layouts/navigation_links' %>

This helper method is pretty awesome because it allows you name a route and then target all of your link locations to your routes.rb file. This is particuarly great you’re moving your website from say, www.cats.com to a new and improved dynamic website that follows RESTful conventions, like maybe www.supercutekittens.com. Imagine having to create absolute URLs for every single link on that website! Ok, don’t panic, you don’t have to.


When you generate a scaffold or a controller(rails g scaffold or rails g controller), Rails also generates a JavaScript/CoffeeScript file and a CSS/SCSS file for that controller! This means that when I make my CatsController, Rails will also add a new file at app/assets/javascripts/cats.js.coffee and another at app/assets/stylesheets/cats.css.scss.


  • Keeping your assets in their proper place will make you a happier and more organized programmer.
  • The Asset Pipeline will make your application perform better. Remember that it’s easier (and faster) for your browser to request one large file from the server, rather than a ton of small ones.
  • Other things to look into: Fingerprinting, which makes the name of a file dependent purely on its content. When the file contents change, the filename also changes.
  • The Asset Pipeline is magical, yet super difficult to learn. You probably won’t understand everything all at once. But hopefully you feel a less confused than this little guy. He’s clearly had too much pipeline for one day: