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
Gemfile
:gem 'requirejs-rails'
-
Remove all Sprockets directives such as
//= require jquery
fromapplication.js
and elsewhere. Instead establish JavaScript dependencies using AMD-styledefine()
andrequire()
calls. -
Use
requirejs_include_tag
at the top-level of your app's layout(s).javascript_include_tag
should be used to reference your top-level JavaScript modules. Other modules will be pulled in dynamically byrequire.js
in development and byr.js
for optimized production builds. Here's a basicapp/views/layouts/application.html.erb
modified forrequirejs-rails
:<!DOCTYPE html> <html> <head> <title>Frobnitz Online</title> <%= stylesheet_link_tag "application" %> <%= requirejs_include_tag %> <%= javascript_include_tag "application" %> <%= csrf_meta_tags %> <meta charset="utf-8"> </head> <body> <%= yield %> </body> </html>
-
Organize your JavaScript or CoffeeScript code into modules using
define()
:# app/assets/javascripts/views/tweet_view.js.coffee define ['backbone'], (Backbone) -> class TweetView extends Backbone.View # ...
-
Instantiate your app using
require()
from a top-level module such asapplication.js
:# app/assets/javascripts/application.js.coffee require ['jquery', 'backbone', 'TheApp'], ($, Backbone, TheApp) -> # Start up the app once the DOM is ready $ -> window.App = new TheApp() Backbone.history.start pushState: true window.App.start()
-
When ready, build your assets for production deployment as usual.
requirejs-rails
defaults to a single-file build ofapplication.js
. Additional modules and r.js layered builds may be specified viaconfig\requirejs.yml
; see the Configuration section below.rake assets:precompile
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.
I currently recommend placing your AMD libraries into vendor/assets/javascripts
. The needs of a few specific libraries are discussed below.
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:
# app/assets/javascripts/hello.js
define ['jquery'], ($) ->
(id) ->
$(id).append('<div>hello!</div>')
Backbone AMD support is underway. See pull request jashkenas/backbone#710 for details. In the meantime, you can download Backbone 0.5.3 with AMD support from jrburke's optamd3 branch. Backbone's module name is backbone
.
Underscore version 1.2.2 or later has integrated AMD support. Get it from Underscore.js' homepage. Underscore's module name is underscore
.
Usage changes that impact folks upgrading along the 0.x series are documented here.
application.js
is configured as the default top-level module for r.js builds.- It is no longer necessary or desirable to specify
baseUrl
explicitly in the configuration. - Users should migrate application configuration previously in
application.js
(alarequire.config(...)
) toconfig/requirejs.yml
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.