RequireJS for Rails
Integrates RequireJS into the Rails 3 Asset Pipeline.
UPGRADE NOTES: Users upgrading within the 0.x series should read the Changes section for relevant usage changes. We're pushing hard to 1.0, when the configuration and setup details will be declared stable. Until that time expect some bumps as things bake out.
Add this to your Rails app's
Remove all Sprockets directives such as
//= require jqueryfrom
requirejs_include_tagat the top-level of your app's layout(s). Other modules will be pulled in dynamically by
require.jsin development and for production builds optimized by
r.js. Here's a basic
<!DOCTYPE html> <html> <head> <title>Frobnitz Online</title> <%= stylesheet_link_tag "application" %> <%= requirejs_include_tag "application" %> <%= csrf_meta_tags %> <meta charset="utf-8"> </head> <body> <%= yield %> </body> </html>
Instantiate your app using
require()from a top-level module such as
When ready, build your assets for production deployment as usual.
requirejs-railsdefaults to a single-file build of
application.js. Additional modules and r.js layered builds may be specified via
config\requirejs.yml; see the Configuration section below.
Configuration lives in
config/requirejs.yml. These values are inspected and used by
requirejs-rails and passed along as configuration for require.js and
r.js. This replaces the use of
require.config() in v0.0.2. The default configuration declares
application.js as the sole top-level module. This can be overridden by creating a
config/requirejs.yml, such as:
modules: - name: 'mytoplevel'
You may pass in require.js config options as needed. For example, to add path parameters:
paths: d3: "d3/d3" "d3.time": "d3/d3.time"
Only modules specified in the configuration will be created as build artifacts by
r.js. Layered r.js builds be configured like so:
modules: - name: 'appcommon' - name: 'page1' exclude: ['appcommon'] - name: 'page2' exclude: ['appcommon']
As a guideline, each module in the configuration should either be referenced by a
requirejs_include_tag in a template or pulled in via a dynamic
require() call. Modules which are solely referenced by a dynamic
require() call (i.e. a call not optimized by r.js) must be specified in the modules section in order to produce a correct build.
Using AMD libraries
I currently recommend placing your AMD libraries into
jQuery users must use jQuery 1.7 or later (
jquery-rails >= 1.0.17) to use it as an AMD module with RequireJS. To use jQuery in a module:
DO NOT USE vanilla Backbone 0.5.3 with require.js!
Backbone with AMD support hasn't been released yet. In the meantime, you can download Backbone 0.5.3 with AMD support from jrburke's optamd3 branch. See pull request documentcloud/backbone#710 for details. Backbone's module name is
Underscore version 1.2.x, 1.2.2 or later has integrated AMD support. Get it from Underscore.js' homepage. Underscore's module name is
IMPORTANT: Underscore has removed AMD support again in the 1.3.x series. Please consult the requirejs mailing list for the current recommended solution.
Usage changes that impact folks upgrading along the 0.x series are documented here.
requirejs_include_tagnow generates a data-main attribute if given an argument, ala:
<%= requirejs_include_tag "application" %>
This usage is preferred to using a separate
application.jsis configured as the default top-level module for r.js builds.
- It is no longer necessary or desirable to specify
baseUrlexplicitly in the configuration.
- Users should migrate application configuration previously in
See the Changelog for other details
- Sample app, including jQuery usage
- Generator and/or template support.. ?
Copyright 2011 John Whitley. See the file MIT-LICENSE for terms.