AssetPackager – JavaScript and CSS Asset Compression for Production Rails Apps

Add to del.icio.us

“We send down exactly one .js and one .css file. If you are sending down more than one of each of these to the browser, you have a performance problem. Fix it with asset packager.” – Pivotal Labs

Description

When it comes time to deploy your new web application, instead of sending down a dozen javascript and css files full of formatting and comments, this Rails plugin makes it simple to merge and compress JavaScript and CSS down into one or more files, increasing speed and saving bandwidth.

When in development, it allows you to use your original versions and retain formatting and comments for readability and debugging.

Because not all browsers will dependably cache javascript and css files with query string parameters, AssetPackager writes a timestamp or subversion revision stamp (if available) into the merged file names. Therefore files are correctly cached by the browser AND your users always get the latest version when you re-deploy.

This code is released under the MIT license (like Ruby). You’re free to rip it up, enhance it, etc. And if you make any enhancements, I’d like to know so I can add them back in. Thanks!

Add / View Comments

Credit

This Rails Plugin was inspired by Cal Henderson’s article Serving Javascript Fast on Vitamin.

It also uses the Ruby Javascript Minifier created by Douglas Crockford and translated to Ruby by Uladzislau Latynski.

Key Features

Merges and compresses javascript and css when running in production.
Uses uncompressed originals when running in development.
Handles caching correctly. (No querystring parameters – filename timestamps)
Uses subversion revision numbers instead of timestamps if within a subversion controlled directory.
Guarantees new version will get downloaded the next time you deploy.

Components

Rake Task for merging and compressing JavaScript and CSS stylesheets.
Helper functions for including these javascript and css files in your RHTML.
YAML configuration file for mapping javascript and css files to merged versions.
Rake Task for auto-generating the YAML file from your existing javascript and css files.

How to Use

1. Download and install the plugin:

   script/plugin install git://github.com/sbecker/asset_packager.git

2. Run the rake task asset:packager:create_yml to generate the /config/asset_packages.yml file the first time. You will need to reorder files under ‘base’ so dependencies are loaded in correct order. Feel free to rename or create new packages.

Example from a fresh rails app after running the rake task. (Stylesheets is blank because a default rails app has no stylesheets yet):

--- 
javascripts: 
- base: 
  - prototype
  - effects
  - dragdrop
  - controls
  - application
stylesheets: 
- base: []

More complex example with multiple packages:

---
javascripts:
- base:
  - prototype
  - effects
  - controls
  - dragdrop
  - application
- secondary:
  - foo
  - bar
stylesheets:
- base:
  - screen
  - header
- secondary:
  - foo
  - bar

3. Run the rake task asset:packager:build_all to generate your merged and compressed packages. Whenever you rearrange the yaml file, you’ll need to run this task again. Merging and compressing is expensive, so this is something we want to do once at deployment, not every time your app starts. Thats why its a rake task.

3. Use the helper function whenever including these files in your application. See examples Below.

Javascript Examples:

Example calls

either by package name:

  <%= javascript_include_merged :base %>

or by the individual assets:

  <%= javascript_include_merged 'prototype', 'effects', 'controls', 'dragdrop', 'application' %>

Output in development:

  <script type="text/javascript" src="/javascripts/prototype.js"></script>
  <script type="text/javascript" src="/javascripts/effects.js"></script>
  <script type="text/javascript" src="/javascripts/controls.js"></script>
  <script type="text/javascript" src="/javascripts/dragdrop.js"></script>
  <script type="text/javascript" src="/javascripts/application.js"></script>

Output in production:

  <script type="text/javascript" src="/javascripts/base_1150571523.js"></script>

Symbols work too, as does :defaults

  <%= javascript_include_merged :defaults %>
  <%= javascript_include_merged :foo, :bar %>

Stylesheet Examples

Example call:

either by package name:

  <%= stylesheet_link_merged :base %>

or by the individual assets:

  <%= stylesheet_link_merged 'screen', 'header' %>

Output in development:

  <link href="/stylesheets/screen.css" media="screen" rel="Stylesheet" type="text/css" />
  <link href="/stylesheets/header.css" media="screen" rel="Stylesheet" type="text/css" />

Output in production:

  <link href="/stylesheets/base_1150729166.css" media="screen" rel="Stylesheet" type="text/css" />

Capistrano Integration

If you want to run the asset:packager:build_all task at deployment time within Capistrano, add this to config/deploy.rb:

task :after_symlink, :roles => [:app] do
  run "cd #{current_path} && rake asset:packager:build_all RAILS_ENV=production"
end

~~That’s the idea anyway. I haven’t had time to test Capistrano integration yet, so if someone could let me know if that works, I’d appreciate it. Otherwise, I’ll test it and add it here soon.~~ Thanks to Fabien Atelier for getting the correct syntax there. Now your asset packages will get built whenever you deploy!

Capistrano Update

François Beausoleil suggests using Capistrano’s “after_update_code” task instead of “after_symlink”, “because as soon as the symlink is done, it means we’re live. We haven’t yet built the files, so users will receive 404s instead of the compressed files.”

So, here’s his recommended Capistrano code, that’ll get the compressed assets built BEFORE your new version is live. :)

task :after_update_code, :roles => [:web] do
  run <<-EOF
    cd #{release_path} &&
    rake RAILS_ENV=production asset:packager:build_all
  EOF
end

Capistrano 2

Thanks to Johannes Holzer for this Capistrano 2 version:

namespace :deploy do
 desc "Create asset packages for production" 
 task :after_update_code, :roles => [:web] do
   run <<-EOF
     cd #{release_path} && rake RAILS_ENV=production asset:packager:build_all
   EOF
 end
end

Contributions

Ticket Tracker – Asset Packager now has a tracker where you can submit tickets. If you have a bug to report or a patch for AssetPackager, this is the place!