Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Sprockets JavaScript dependency management and concatenation support for Rails applications

branch: master

This branch is 0 commits ahead and 0 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.textile

Sprockets-rails

Sprockets-rails sets up your Rails application for use with Sprockets.

Installation

The first thing you need to do is install the Sprockets RubyGem. Just run;

gem install --remote sprockets

For more information about installing and using Sprockets, check out the Sprockets website and the Sprockets github project.

Sprockets-rails can be installed as a gem or as a plugin;

Installing as a gem

Add this to your environment.rb file;

config.gem 'sprockets-rails', :source => 'http://gemcutter.org'

And run;

rake gems:install

Once the gem is installed, run the generator and you’re all set;

script/generate sprockets_rails

The gem is now installed and the required files and folders will be generated into your project.

Installing as a plugin

Run this in the root of your Rails project;

script/plugin install git://github.com/80beans/sprockets-rails.git

The plugin will get installed and the required files and folders will be generated into your project.

Usage

Now you have sprockets-rails installed as a gem or a plugin. You now have app/javascripts/ and vendor/sprockets/ directories in your application, as well as a config/sprockets.yml file.

Edit your config/routes.rb file to add routes for SprocketsController:

ActionController::Routing::Routes.draw do |map|
  # Add the following line:
  SprocketsApplication.routes(map) 
  ...
end

Now, move your JavaScript source files from public/javascripts/ into app/javascripts/. All files in all subdirectories of app/javascripts/ will be required by Sprockets in alphabetical order, with the exception of app/javascripts/application.js, which is required before any other file_. (You can change this behavior by editing the @sourcefiles@ line of config/sprockets.yml.)

The last thing you’ll have to do is adjust your HTML templates to call <%= sprockets_include_tag %> instead of <%= javascript_include_tag ... %>.

Once sprockets-rails is installed, you can check out Sprockets plugins into the vendor/sprockets/ directory. By default, sprockets-rails configures Sprockets’ load path to search vendor/sprockets/*/src/, as well as vendor/plugins/*/javascripts/. This means that the javascripts/ directories of Rails plugins are automatically installed into your Sprockets load path

Using multiple sprockets configurations in a project

Edit your config/sprockets.rb file to name the configurations:

:default:
  :asset_root: public
  :load_path:
    - app/javascripts
    - vendor/sprockets/*/src
    - vendor/plugins/*/javascripts
  :source_files:
    - app/javascripts/application.js
:special:
  :asset_root: public
  :load_path:
    - app/javascripts
    - vendor/sprockets/*/src
    - vendor/plugins/*/javascripts
  :source_files:
    - app/javascripts/special.js

Now, adjust your HTML templates to call <%= sprockets_include_tag(:config_name) %> with the name of the configuration you wish to use. Concatenations are located at RAILS_ROOT/sprockets/<config_name>.js, except for the default configuration, whose concatenation located at RAILS_ROOT/sprockets.js.

How it works

Sprockets-rails includes a controller named SprocketsController that renders your application’s Sprockets concatenation. When caching is enabled, e.g. in production mode, SprocketsController uses Rails page caching to save the concatenated output to public/sprockets.js the first time it is requested. When caching is disabled, e.g. in development mode, SprocketsController will render a fresh concatenation any time a source file changes.

To source Sprockets’ JavaScript concatenation from your HTML templates, use the provided sprockets_include_tag helper.

Sprockets-rails also includes a set of Rake tasks for generating the concatenation (rake sprockets:install_script) and installing provided assets (rake sprockets:install_assets). Run sprockets:install_assets any time you add or update a Sprockets plugin in your application. Add after "deploy:update_code", "sprockets:install_script" as a Capistrano post-deploy hook to generate the Sprockets concatenation on your servers automatically at deploy time.

License

Copyright © 2009 Sam Stephenson, released under the MIT license

Something went wrong with that request. Please try again.