Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A tool for optimizing Require.js modules using r.js under the asset pipeline.
JavaScript Ruby Other
tree: b44039c7aa

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
lib
spec
.gitignore
.rspec
.travis.yml
Gemfile
LICENSE
README.md
Rakefile
requirejs_optimizer.gemspec

README.md

RequirejsOptimizer

Build Status

R.js optimization to go with your require.js modules, all under the asset pipeline.

This lib is an extention to the functionality already provided by the asset pipeline. It takes the result of a full assets:precompile and applies the peformance benefits of optimization through R.js.

Installation

Add this line to your application's Gemfile:

gem 'requirejs_optimizer'

And then execute:

$ bundle

Or install it yourself as:

$ gem install requirejs_optimizer

Once the gem is installed, run the install generator:

$ rails g requirejs_optimizer:install

It'll ask you what your main module name should be, but will default to main if left blank. This is referring to the file that will be the main entry point for doing your initial requires.

Once you've ran the install generator, you'll have the following directory/file additions:

app
↳ assets
   ↳ javascripts
      ↳ modules             # new
         ↳ README           # new             
         ↳ main.js.coffee   # new
         ↳ require.build.js # new

require.build.js is the require.js project build file used by r.js. Read more about this here.

For an example build file that contains all available options, check this out.

Usage

Note::This gem does not provide require.js for use in your app - you can get that here.

rake assets:precompile

This runs the normal rails assets:precompile cycle, then:

  • Copies public/assets to tmp/assets
  • Removes all existing digestified and gzipped files
  • Runs the r.js optimization tool with the build file in app/assets/javascripts/modules/require.build.js
  • Re-digests all files
  • Re-gzips all js/css files
  • Writes a new manifest.yml file
  • Copies the resulting build back to pubilc/assets

Quick rundown on require.js, require.build.js and folder structure

Given the following build file that lives under app/assets/javascripts/modules/require.build.js:

({
    appDir:    "../../../../tmp/assets"
    , baseUrl: "./modules"
    , dir:     "../../../../tmp/assets/build"
    , name:    "main"
})

You should have your main require.js module live in app/assets/javascripts/modules/main.js(.coffee).

Given the following contents in main.js.coffee:

require ["one/foo", "two/bar"], (foo, bar) -> # ...

You should have two modules:

  • app/assets/javascripts/modules/one/foo.js.coffee
  • app/assets/javascripts/modules/two/bar.js.coffee

After running rake assets:precompile, modules foo and bar will be compiled into main.js

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes with tests (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Detailed topics

How it's modifying the environment

This lib does a few things to the environment on initialize:

  • It adds all files under app/assets/javascripts/modules to config.assets.precompile. The result is each file under this directory is compiled individually. This is done because R.js needs these files for dependency tracing on build layers.
  • It turns off Sprockets' js and css compression via config.assets.compress = false in favor of letting R.js run the assets through the compression mechanism defined in your build file (uglify by default, see here)
  • It makes available a few rake tasks:

    rake requirejs         # copy `public/assets` to `tmp` and perform the build,
                           # then copy the build result back to `public/assets`
    
    rake requirejs:clean   # remove the `tmp` build directory (`tmp/assets` by default)
    
    rake requirejs:nocopy  # runs `requirejs`, just without the final
                           # => `public/assets` step
    
  • It extends assets:precompile by appending the actions of the requirejs rake task to assets:precompile:nondigest.

    Details...

    Overriding assets:precompile:nondigest in stead of assets:precompile allows asset precompilation to happen on Heroku. It's not entirely clear why the former works and the latter doesn't.

    Also, if you want to run the vanilla assets:precompile without R.js optimization, this should do the trick:

      NO_RJS=true rake assets:precompile
    
Something went wrong with that request. Please try again.