by mintdigital

mintdigital / asset_hat

Load CSS and JS faster in Rails. Your assets are covered.

196 Stars 20 Forks Last release: Not found MIT License 227 Commits 16 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

= AssetHat

Load CSS and JS faster. 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 libraries from the JS community -- like jQuery, YUI, and Dojo -- 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.
  • Load plenty of JS files in parallel in {LABjs}[] mode. When calling includejs, just add :loader => :labjs.
  • 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:

<%= includecss :bundle => 'application' %> <%= includejs :jquery, :bundles => ['plugins', 'common'] %>

Which expands into:

<!-- In production, jQuery loads from Google's CDN instead. -->

Don't have your own copy of jQuery? AssetHat detects this and knows how to load 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 3 and Rails 2.3.x (with Bundler). For a quick overview, see {the AssetHat website}[]. To see how AssetHat performs in production, {check some stats}[]. 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
  1. Add to your app's Rakefile: require 'asset_hat/tasks'

== Quick start & configuration

  1. In all of your layouts and views, change stylesheetlinktag to includecss, and change javascriptincludetag to includejs. (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: %> <%= stylesheetincludetag '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/.

    If you're using a CSS/JS layer like SASS or CoffeeScript, be sure to compile/transpile to regular CSS/JS before running rake assethat:minify. (When AssetHat is ready for Rails 3.1, rake assethat:minify will automatically start with rake assets:precompile.)

=== Advanced configuration

If you manage deployments with Capistrano[], see the gem's packaged example at lib/assethat/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/assethat/unicorn.rb[].

If you want shorter output during deployments, you can use

rake asset_hat:minify FORMAT=short
(one output line per bundle) or
(one output line total) in your deploy script.

Additional settings are supported in config/assets.yml:

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 jqueryui: version: 1.8.12 remoteurl: remotesslurl:

Configuration keys per vendor:

  • version: Sets the default version across the app. In the example above, <%= includejs :jquery %> uses version 1.5.2 by default. You can override this for special layouts/views with <%= includejs :jquery, :version => '1.3.2' %>.
  • remoteurl, remotesslurl: By default, vendor JS will load from {Google's CDN}[] in production (or any environment where config.actioncontroller.considerallrequests_local is set to false). 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.actioncontroller.assethost = do |source, request| "#{request.protocol}cdn#{source.hash % 4}" # => '', '', 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:

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

Use these:

<%= includecss :bundle => 'application' %> <%= includejs :bundle => 'application' %>

These turn into:

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

If your environment has config.actioncontroller.performcaching 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.actioncontroller.assethost 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:

<%= includecss 'reset', 'application' %> <%= includejs 'plugin.min', 'application' %>

Or include multiple bundles at once:

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

When including multiple bundles at once, this yields one or element per bundle.

=== LABjs mode

Say you're loading several JS bundles. However, because there are so many, you decide to try a popular script loader like {LABjs}[] to see how much it improves performance. Here's how it's done the old Rails way:

<%= javascriptincludetag 'LAB-1.2.0.min.js' %>

What a hassle. With AssetHat, just set up a bundle in config/assets.yml:

js: bundles: app: - common - search - app

Ready to go. Here's how to load jQuery and your bundle normally:

<%= include_js :jquery, :bundle => 'app' %>

And here's how to switch on LABjs mode:

<%= includejs :jquery, :bundle => 'app', :loader => :labjs %>

Add your preferred jQuery and LABjs versions to the config file if you haven't already, and that's it. If you don't have a copy of LABjs locally, AssetHat knows how to instead load it from {cdnjs}[], which uses high-speed Amazon Cloudfront servers.

This is just the most common LABjs use case. If you want to fine-tune it even further, you can have the best of both worlds:

<%= includejs :labjs %>

In this example, common is not a dependency for search, so allow either to execute as soon as possible -- whichever happens to load first -- rather than always forcing common to execute first.

=== 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). LABjs mode can help with loading several smaller bundles in parallel. Your own tests will tell what's optimal for your situation.

== More info

  • {Official website}[]
  • {Full documentation}[]
  • {History/changelog}[]
  • Released under the {MIT license}[].

=== Contributing

Have an idea, problem, or bug report? {Send a pull request}[]! Please base pull requests on the

branch, not the


  • {rondevera}
  • {philnash}[]
  • {dstrelau}[]
  • {daphonz}[]
  • {sauliusg}[]
  • {jsonperl}[]

== {What is best in AssetHat?}[]

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.