Rails plugin to allow for compressing and bundling JavaScript & CSS files for production
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 14 commits ahead of voxxit:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Based on the concept sported by GitHub, this plugin serves the purpose of making it much easier to package your JavaScript and CSS files together into “bundles”, so that they are easy for your clients to download once and cache in their browsers. This is a recommended practice to increase performance of your Rails application dramatically.


  • Rails v2.3.8 or v3.0.0b4

Getting Started

There is a simple methodology that needs to be adopted by your application when organising your JavaScript and CSS files:

|-- admin
| |-- date.js
| `-- datePicker.js
|-- common
| |-- application.js
| |-- jquery.tablesorter.js
| `-- jquery.editable.js
|-- dev
  |-- jquery-1.4.1.js
  `-- jquery-ui-1.7.2.js

The directory structure is similar in public/stylesheets, as well. This essentially namespaces your directories so they are easier to organise. You need to only place files that are used in that specific namespace in the directory. If you use the library in more than one namespace, it should be placed in a “common” folder.

The “dev” folder is used locally, and is replaced with a cached version somewhere else on the Internet in production. More on that later…

View Helper Methods

You will need to include a couple of helpers in your layout files:

<%= javascript_dev ['jquery-1.4.1', "http://ajax.googleapis.com/ajax/libs/jquery/1.4.1/jquery.min.js"] %>
<%= javascript_bundle 'common', 'clients' %>
<%= stylesheet_bundle 'common', 'clients' %>

In this instance, there are three helpers: `javascript_dev`, `javascript_bundle` and `stylesheet_bundle`.

  • javascript_dev - In development, the files included in the “dev” directory are included. Otherwise, it sets the cached version using the URL.

  • javascript_bundle - In development, this method does a recursive search for all files in the namespaces listed and includes the raw, uncompressed files. Otherwise, it will look for “bundle_namespace.js” and include this file, if it exists.

  • stylesheet_bundle - Exactly the same as above, but for CSS files.


JavaScript compression is handled using the Closure Compiler by Google, which is included in the bin/ directory. CSS compression is handled by YUI Compressor, also included.

Rake Tasks

Included Rake tasks are:

  • rake assemble:all - Compresses and bundles both CSS & JavaScript

  • rake assemble:js - Only assembles namespaced JavaScript

  • rake assemble:css - Only assembles namespaced CSS


You can handle these tasks on deployment by doing the following:

namespace :deploy do
  desc "Assemble JavaScript and CSS files"
  task :assemble, :roles => :web, :except => { :no_release => true } do
    run "cd #{release_path}; rake assemble:all"

after "deploy:update_code", "deploy:assemble"

Assemblage Configuration and Ordering Files within a Bundle

To order the files within each bundle you may create a file config/assemblage.rb within your Rails application that provides the specific list of files and their order. For example:

bundle :widget, :js, 'jquery-1.4.4.min.js', 'jquery-ui-1.8.7.custom.min.js', 'jquery.maskedinput.js', 'raphael-1.5.2.min.js', 'jquery.ba-postmessage.0.5.min.js'
bundle :app, :js, 'jquery-1.4.4.min.js', 'jquery-ui-1.8.7.custom.min.js', 'farbtastic'
bundle :app, :css, 'site', 'jquery-ui-1.8.7.custom.css', 'farbtastic'

Defines 3 bundles. The first named 'widget' that is a JavaScript bundle that includes 5 files in the order specified, the second 'app' another JavaScript bundle including 3 files in the given order and the last one 'app' a CSS bundle providing 3 css files in the given order. Any bundle not listed in the configuration file will order the included files in alphabetical order.

Issues & Contributions

For all issues and bug/feature requests, please use the GitHub issue tracker:


Additional documentation

Very helpful article: Static Asset Bundling with Ruby on Rails By: Todd Fisher.


Thanks to Kyle Neath for the inspiration to turn his idea into a useful plugin for all!

Copyright © 2010 Josh Delsman, released under the MIT license