Synthesis : Scott Becker

Asset Packager

Note: Asset Packager is deprecated. Rails 3.1 now offers the Asset Pipeline.

JavaScript and CSS Asset Compression for Production Rails Apps

“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.

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

Components

Updates

November ‘08:

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.

Examples of config/asset_packages.yml

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: []

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 the compressed, merged versions for each package. 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, not every time your app starts. Thats why its a rake task. You can run this task via Capistrano when deploying to avoid an initially slow request the first time a page is generated.

Note: The package will be generated on the fly if it doesn’t yet exist, so you don’t need to run the rake task when deploying, its just recommended for speeding up initial requests.

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

Javascript Examples:

Example calls

<%= javascript_include_merged :base %>
<%= 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_packaged.js?123456789"></script>

Symbols work too, as does :defaults

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

Stylesheet Examples

Example call:

<%= stylesheet_link_merged :base %>
<%= 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_packaged.css?123456789" media="screen" rel="Stylesheet" type="text/css" />

Capistrano 2.X Integration

Building the packages at deployment time will help speed up initial requests. This is not strictly necessary as packages will be built on the fly if they are not found.

If you want to run the asset:packager:build_all task at deployment time within Capistrano, add this task to your Capistrano recipe:

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

Contributions

Blog Posts about Asset Packager

Leave a comment