Section 9.4. Asset Packaging

9.4. Asset Packaging

Complex Ajax applications often entail dozens of JavaScript and CSS files, and generally each one is downloaded separately. Even if each file is small, the network overhead of requesting so many files can have a significant impact on the load time for a page. Client-side caching doesn't eliminate the issue, because the browser still needs to check to see if the cache is up-to-date, so it's subject to network latency. The solution is to reduce the total number of files needed for a complete page load, which means merging separate JavaScript and CSS files.

You could join the files into one by hand, but that makes development more difficultit's far easier to have JavaScript and CSS files divided up according to their purpose.

Why not let Rails take care of it for you? That's what the Assert Packager plug-in was designed for. It allows you to maintain as many JavaScript and CSS files as you like for development, but merge them in production. The entire process is easily automated, so that users will be guaranteed to get the latest version of each file but won't be forced to re-download anything that hasn't changed.

To install the Asset Packager plug-in, use script/plugin from the command prompt:

script/plugin install http://sbecker.net/shared/plugins/asset_packager

Once it's installed, create an Assert Packager configuration file by running:

rake asset:packager:create_yml

That rake task will examine your current JavaScript and CSS files and configure a package for both kinds of files. To control the order that the files will be included in the page, edit config/asset_packages.yml.

When you're satisfied with the configuration, generate the merged files by running another rake task:

rake asset:packager:build_all

Next, just edit your layouts to use the plug-in's helpers. Instead of the usual javascript_include_tag and stylesheet_link_tag helpers, use javascript_include_merged and stylesheet_link_merged, passing them the name of the packages you want loaded. For example:

<%= javascript_include_merged :base %> <%= stylesheet_link_merged :base %>

When running in development, the output will look like this:

<script src="/books/4/386/1/html/2//javascripts/unittest.js" type="text/javascript"></script> <script src="/books/4/386/1/html/2//javascripts/prototype.js" type="text/javascript"></script> <script src="/books/4/386/1/html/2//javascripts/effects.js" type="text/javascript"></script> <script src="/books/4/386/1/html/2//javascripts/dragdrop.js" type="text/javascript"></script> <script src="/books/4/386/1/html/2//javascripts/controls.js" type="text/javascript"></script> <script src="/books/4/386/1/html/2//javascripts/builder.js" type="text/javascript"></script> <script src="/books/4/386/1/html/2//javascripts/application.js" type="text/javascript"></script> <link href="/stylesheets/application.css" media="screen" rel="Stylesheet" type="text/css" />

But in the production environment, the output will be reduced to something like this:

<script src="/books/4/386/1/html/2//javascripts/base_1154907074.js" type="text/javascript"></script> <link href="/stylesheets/base_1.css" media="screen" rel="Stylesheet"  type="text/css" />

To get the full benefit of asset packaging, the last step is to configure your deployment script to automatically rebuild the asset packages during deployment. For more information about using Asset Packager with Capistrano (the Rails-standard deployment automation tool), refer to Asset Packager's online documentation: http://synthesis.sbecker.net/pages/asset_packager.