README.rdoc
README.rdoc
Last Update: Sun Apr 24 13:42:43 -0400 2011

AssetHat

Your assets are covered.

With Rails’ default asset caching, CSS and JS are concatenated (not even minified) at runtime when that bundle is first requested. Not good enough. To make your pages load faster, AssetHat can automatically:

  • Easily minify and bundle CSS and JS to reduce file sizes and HTTP requests. Do this on deploy, and avoid any performance hit at runtime.
  • Load popular third-party JS (like jQuery, YUI, and Ext JS) from Google's CDN when in production, or from localhost in development. It’s as simple as <%= include_js :jquery %> to load straight from Google.
  • Force image URLs in your CSS to use CDN subdomains (including SSL support), not just the current host.
  • Add an image’s last Git commit ID to its CSS URLs to bust browser caches (e.g., /images/foo.png?ab12cd3).

After setup, you can use this in your layouts and views: 

<%= include_css :bundle => 'application' %>
<%= include_js  :jquery, :bundles => ['plugins', 'common'] %>

Which expands into: 

<link href="/stylesheets/bundles/application.min.css"
  media="screen,projection" rel="stylesheet" type="text/css" />
<script src="/javascripts/jquery-1.x.x.min.js"
  type="text/javascript"></script>
  <!-- In production, jQuery loads from Google's CDN instead. -->
<script src="/javascripts/bundles/plugins.min.js"
  type="text/javascript"></script>
<script src="/javascripts/bundles/common.min.js"
  type="text/javascript"></script>

Don’t have your own copy of jQuery? AssetHat detects this and loads jQuery from Google’s CDN instead, whether you’re in development or production.

Add this to your deploy script, and your CSS/JS will be optimized automatically: 

rake asset_hat:minify

Tested with Rails 2.3.x. For a quick overview, see the AssetHat website. For the gritty details, check the complete docs and change history.

Installation

  • Rails 3.x:
    1. Add to your app’s Gemfile: gem 'asset_hat', '0.x.x'
    2. Command-line: bundle install
  • Rails 2.3.x:
    1. Add the gem:
      • If you’re using Bundler 0.9+:
        1. Add to your app’s Gemfile: gem 'asset_hat', '0.x.x'
        2. Command-line: bundle install
      • If you’re using Rails 2.3.x’s config.gem:
        1. Add to your app’s config/environment.rb: config.gem 'asset_hat', :version => '0.x.x'
        2. Command-line: gem install asset_hat
    2. Add to your app’s Rakefile: require 'asset_hat/tasks'

Quick start & configuration

  1. In all of your layouts and views, change stylesheet_link_tag to include_css, and change javascript_include_tag to include_js. (Don’t worry, these helpers use the same arguments as Rails’ helpers. Nothing will break.)
  2. Create the default config file: 
    rake asset_hat:config
  3. In your app, open the new file at config/assets.yml, and set up your CSS/JS bundles according to that file’s example.
  4. In your layouts and views, switch to the new bundles. For example, if you originally had this: 
    <%# app/views/layouts/application.html.erb: %>
<%= stylesheet_include_tag 'reset', 'application' %>

    Then you’ll now have: 

    # config/assets.yml:
css:
  bundles:
    application: ['reset', 'application']

<%# app/views/layouts/application.html.erb: %>
<%= include_css :bundle => 'application' %>
  5. Add this to your deployment script: 
    rake asset_hat:minify

    This minifies all of the CSS/JS files listed in config/assets.yml, concatenates the minified code into bundle files, and adds CDN asset hosts and cache-busting commit IDs to image URLs in your CSS.

    Any previously minified bundles are overwritten; your original CSS/JS files remain untouched. Bundles are created as new files in public/stylesheets/bundles/ and public/javascripts/bundles/.

Advanced configuration

If you manage deployments with Capistrano, see the gem’s packaged example at lib/asset_hat/capistrano.rb.

If your stack uses Unicorn, you’ll want to configure it so that assets’ commit IDs are precached only once. See the gem’s packaged example at lib/asset_hat/unicorn.rb.

If you want shorter output during deployments, you can use `rake asset_hat:minify FORMAT=short` (one output line per bundle) or `FORMAT=dot` (one output line total) in your deploy script.

Additional settings are supported in config/assets.yml:

  • engine: Indicates how CSS and JS are minified; omit this setting to use the defaults. By default, CSS is minified with rgrove/cssmin (a Ruby port of Lecomte’s YUI Compressor and Schlueter’s PHP cssmin), and JS is minified with rgrove/jsmin (a Ruby port of Crockford’s JSMin).

    If you’d prefer to have slightly more readable code for debugging purposes, you can switch both the CSS and JS engines to weak. However, the weak engines don’t save as many bytes.

  • vendors: Configures third-party JS that’s loaded from a CDN or other external source. The following example configures jQuery and jQuery UI for use throughout the app: 
    js:
  vendors:
    jquery:
      version:        1.5.2
    jquery_ui:
      version:        1.8.12
      remote_url:     http://cdn.example.com/js/jquery-ui-1.8.12.min.js
      remote_ssl_url: https://cdn-ssl.example.com/js/jquery-ui-1.8.12.min.js

    Configuration keys per vendor:

    • version: Sets the default version across the app. In the example above, <%= include_js :jquery %> uses version 1.5.2 by default. You can override this for special layouts/views with <%= include_js :jquery, :version => '1.3.2' %>.
    • remote_url, remote_ssl_url: By default, vendor JS will load from Google's CDN in production (or any environment where config.action_controller.consider_all_requests_local is set to true). If the original request to your app used SSL, the vendor JS will also load from Google’s CDN via SSL. If you prefer to use a different CDN, specify its SSL/non-SSL URLs, and the appropriate URL will be used per request.

    A full list of supported vendors is in the AssetHat::JS::Vendors module.

SSL configuration

When you request a page via SSL, some browsers (euphemism for “IE”) show errors if any assets — stylesheets, JS files, images — are served without SSL.

AssetHat plays well with SSL pages that load assets from a CDN. Put this in config/environments/production.rb or similar: 

config.action_controller.asset_host = Proc.new do |source, request|
  "#{request.protocol}cdn#{source.hash % 4}.example.com"
    # => 'http://cdn0.example.com', 'https://cdn1.example.com', etc.
end

This switches to a different CDN URL if the request used SSL. When you run rake asset_hat:minify at deploy time, AssetHat detects this configuration, and generates special SSL versions of each stylesheet that also load images from CDN via SSL. (Non-SSL pages still get non-SSL stylesheets.)

Usage

In your layouts and views, instead of these: 

<%= stylesheet_link_tag 'reset', 'application', 'clearfix',
                        :media => 'screen,projection',
                        :cache => 'bundles/application' %>
<%= javascript_include_tag 'plugin-1', 'plugin-2', 'plugin-3',
                           :cache => 'bundles/application' %>

Use these: 

<%= include_css :bundle => 'application' %>
<%= include_js  :bundle => 'application' %>

These turn into: 

<link href="/stylesheets/bundles/application.min.css"
  media="screen,projection" rel="stylesheet" type="text/css" />
<script src="/javascripts/bundles/application.min.js"
  type="text/javascript"></script>

Have an enormous app? You can integrate gradually, using AssetHat alongside Rails’ default asset caching.

If your environment has config.action_controller.perform_caching set to true (e.g., in production), the layout/view will include minified bundle files. Otherwise, the separate, unminified files will be included, based on the bundle contents you define in config/assets.yml.

If your environment has config.action_controller.asset_host pointing to a CDN, your CSS/JS files will load from there. If your configuration supports using the CDN via SSL (see the section “SSL configuration”), SSL requests will also load CSS/JS files via SSL.

Advanced usage

You can also include single files as expected: 

<%= include_css 'reset', 'application' %>
<%= include_js  'plugin.min', 'application' %>

Or include multiple bundles at once: 

<%= include_js :bundles => %w[plugins common] %>

When including multiple bundles at once, this yields one <link> or <script> element per bundle.

Bundle tips

Don’t go overboard with huge bundles:

  • Mobile browsers may not cache CSS/JS files that are too large, regardless of gzipping. Check the latest specs for each mobile browser you support.
  • You might want to put plugins (rarely changed) in one bundle, and application code (frequently changed) in another bundle. This way, when the app code changes, the browser re-downloads only the new app code, and uses the cached plugin code.
  • Regardless of code-change frequency, it’s sometimes faster to split a bundle in half, and load each half in parallel (i.e., two HTTP requests instead of one). Your own tests will tell what’s optimal for your situation.

What is best in AssetHat?

  • To crush your assets;
  • See them bundled before you; and
  • Hear no more lamentation about slow page loads.