It is part of the RequireJS project, and works with the RequireJS implementation of AMD.
r.js is a single script that has two major functions:
- Run AMD-based projects in Node and Rhino.
- Includes the RequireJS Optimizer that combines scripts for optimal browser delivery.
Releases of r.js are kept in the dist directory. To build your own from the files in this repo, run:
That will generate an r.js file in the same directory as dist.js
Running AMD-based projects
If your JS project's main application file is called main.js, then do the following:
node path/to/r.js main.js
Requires Node 0.4 or later.
r.js allows using Node modules installed via npm. For more info see the Use with Node docs.
Java requires some JAR files in the CLASSPATH for it to work:
- rhino.jar from the Rhino project.
- compiler.jar if you are using the optimizer and want to use Closure Compiler.
Download those files to your machine. To run r.js, you can use this type of command:
All further examples will use the Node notation, but substitute node r.js in the commands with the appropriate java command.
The optimizer can be run by passing the -o command to r.js:
node r.js -o path/to/buildconfig.js
See the Optimization doc for more information on the optimizer.
If running in Java, be sure to grab the Rhino and Closure Compiler jar files in the lib/ directory, then run this command:
What makes it special
The optimizer is better than using a plain concatenation script because it runs require.js as part of the optimization, so it knows how to:
- Use Loader Plugins to load non-script dependencies and inline them in built files.
- Name anonymous modules. If your optimization step does not do this, and you use anonymous modules, you will get errors running the built code.
Other r.js commands
To get the version of r.js and the version of require.js used by r.js:
node r.js -v
Convert CommonJS modules
To convert a directory of CommonJS modules to ones that have define() wrappers:
node r.js -convert path/to/commonjs/dir output/dir
Most, but not all, CommonJS modules can be converted to define()-wrapped modules and still work.
However, there are some modules that may fail if:
- They use code branches like if/else or try/catch to call require(). There are problems supporting this kind of dynamic module calls in an async environment.
- Some kinds of circular dependencies will not work right. The kinds that fail are normally very brittle and depend on the execution order of the dependent modules.
NOTE: If you clone this repository, it must be a sibling to a clone of the RequireJS repository, where that repository is called requirejs. Otherwise the tests will not run.
- dist.js: the script that builds r.js
- require.js: the version of require.js to include in r.js
- dist the directory containing releases of r.js
- build: The files that make up the optimizer. dist.js includes a list of the files from this directory to build into r.js.
- lib: The Java libraries for Rhino and Closure Compiler. Only needed if using Java/Rhino to run r.js
- tests: command line tests. Run it under Node and Rhino by doing ../r.js all.js
dist.js takes the build/jslib/x.js file and injects the require.js files and other files from the build/jslib directory into it.
If you make changes to any of those files, you will need to run node dist.js to generate a new r.js. Be sure to run it through the tests , using both Node and Java/Rhino:
Contributing code changes
See the RequireJS Contributing page for info on how to contribute code/bug fixes to this project.
Use GitHub pull requests to point to code changes, although for larger changes, contact the requirejs mailing list to discuss them first.
r.js includes modules from these projects:
Doing a release
To do a release of version 0.0.0:
- git checkout -b 0.0.0
- Make sure the right version of require.js is in the project.
- Modify build/jslib/x.js to update the r.js version number in two places.
- node dist.js
- Run the tests (see above). They should pass. :)
- mv r.js dist/r-0.0.0.js
- git add dist/r-0.0.0.js
- git commit -a -m "Release 0.0.0"
- git tag -am "Release 0.0.0" 0.0.0
- git checkout master
- git merge 0.0.0
- git push origin master
- git push --tags
- git branch -d 0.0.0
Update the RequireJS download site to point to the latest release.