Asset Pipeline

Dependency Management

Sprockets is a tool for managing libraries of JavaScript (and CoffeeScript) code, declaring dependency management and include 3rd-party code. At its core, Sprockets makes a require method available inside your .js and .coffee files which can pull in the contents of an external file from your project or from a 3rd party gem.

Say I have a file called jquery.js which contains the jQuery library and another file called app.js which contains my application code. My app file can include jquery before it runs like so:

//= require "jquery"

$(document).ready(function() {
  $(".item").pluginCode({
    param1: true,
    param2: "maybe"
  });
});

This system also works within CSS files:

/*
 *= require base
 */

body {
  font-weight: bold;
}

If you're using Sass you should stick with Sass' @import rule rather than using Sprockets directives.

Deploying combined assets only

If you prefer to deploy only the combined (concatenated) assets to the build directory with middleman build command, you should use the underscore-names for your ingredient assets. Example: the main /source/javascripts/all.js file is used for all dependencies:

//= require "_jquery"
//= require "_my_lib_code"
//= require "_my_other_code"

and the /source/javascripts/ directory should contain files: _jquery.js, _my_lib_code.js, _my_other_code.js. The resulting /build/javascripts/ directory will contain the all.js file only, with all dependant code included.

Asset Gems

You can use assets from gems by including them in your Gemfile, like this:

gem "bootstrap-sass", :require => false

The :require => false bit is important - many of these gems assume you're running in Rails, and break when they try to hook into Rails' or Compass' internals. Just avoid requiring the gems and Middleman will take care of the rest.

Once you've added a dependency on these gems, any images and fonts from the gem will be included in your project automatically. JavaScript and CSS are also available to be requireed or @imported into your own files.

If you want to refer to a gem stylesheet or JS file directly from your HTML rather than including it in your own assets, you'll need to import it explicitly in config.rb:

sprockets.import_asset 'jquery-mobile'

Then you can refer to that asset directly from script tags or javascript_include_tag.

Sprockets Import Path

If you have assets in directories other than your :js_dir or :css_dir, you can make them importable by adding them to your Sprockets import path. Add this to your config.rb:

sprockets.append_path '/my/shared/assets/'

Sprockets supports Bower, so you can add your Bower components path directly:

sprockets.append_path File.join root, 'bower_components'

Compass

Middleman comes with Compass support out of the box. Compass is a powerful framework for writing cross-browser stylesheets in Sass. Compass also has its own extensions, like Susy, which you can use in Middleman. All of Sprockets' path helpers like image-url are hooked into the Middleman Sitemap, so other extensions (like :asset_hash) will affect your stylesheets too.