README.md

RequireJS for Rails

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.

Usage

Add this to your Rails app's Gemfile:

gem 'requirejs-rails'

Remove all Sprockets directives such as //= require jquery from application.js and elsewhere. Instead establish JavaScript dependencies using AMD-style define() and require() calls.

Use requirejs_include_tag at the top-level of your app's layout(s). Other modules will be pulled in dynamically by require.js in development and for production builds optimized by r.js. Here's a basic app/views/layouts/application.html.erb modified for requirejs-rails:

When ready, build your assets for production deployment as usual.
requirejs-rails defaults 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.

rake assets:precompile

Configuration

The Basics

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. The default configuration declares application.js as the sole
top-level module. This can be overridden by creating
a config/requirejs.yml, such as:

In this example, only modules page1 and page2 are intended for direct
loading via requirejs_include_tag. The appcommon module contains
dependencies shared by the per-page modules. As a guideline, each module in
the configuration should be referenced by one of:

A requirejs_include_tag in a template

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.

Be a common library module like appcommon, listed in the priority config
option.

Almond support

This gem supports single-file builds with
almond. Use the following setting in
application.rb to enable it:

config.requirejs.loader =:almond

Almond builds have the restriction that there must be exactly one modules entry in
requirejs.yml. Typically the wrap option will be used to create a self-contained build:

modules:
- name: 'main'wrap: true

Build-time asset filter

The requirejs-rails build process uses the Asset Pipeline to assemble assets
for the r.js build. By default, assets ending in .js, .html, and .txt
will be made available to the build. If you have other asset suffixes to
include, use the logical_asset_filter config setting to add them.

The asset_sync gem is one
tool that can be used to deploy your built assets to a CDN (S3, in this
case).

Troubleshooting

Avoid config.assets.precompile

Don't set config.assets.precompile to reference any of your AMD module code.
Avoid it altogether, except to reference non-AMD code that you're loading via
javascript_include_tag, and which is never referenced by the AMD codebase.

Using AMD libraries

I currently recommend placing your AMD libraries into
vendor/assets/javascripts. The needs of a few specific libraries are
discussed below.

jQuery

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: