Justin McCandless

Requirejs is great for breaking up JavaScript projects into multiple files, but what happens when you want to use your Requirejs code in another project? Ideally, no one should have to individually import your modules, or even use Requirejs at all. Luckily this is all part of the plan for Requirejs projects, and with a bit of tweaking with the finicky r.js tool, you'll be able to build to a single file with no dependencies.

Setup

We'll be using two tools to do this: the command line r.js tool, and almond. Feel free to use Grunt or Gulp with their respective Requirejs plugins grunt-contrib-requirejs and gulp-module-requirejs instead of the command line tool itself, as the config is exactly the same, but in this article we'll use the command line tool for simplicity.

Start off by installing r.js via npm:

npm install -g requirejs

Also grab the almond.js file either from the repo or from bower:

bower install almond

The Command Line Tool

You can find the official documentation for compiling a Requirejs project into one file under the optimization section of the Requirejs site. That means we're talking exclusively about using r.js with the -o flag, which is used like this:

r.js -o 

Your build configuration can be one of two things. It can be a path to your build file, or it can be your series of options directly on the command line. In this article we're going to use a separate build file for clarity, but first an important distinction:

Your main Requirejs file is not the same thing as your build file.

You've probably written a main file for Requirejs before that looks something like this:

The config section might look similar to some of the build parameters given on the Requirejs site under optimization, but this is not what's used directly by r.js -o; you need a separate build configuration.

Build Config

The Requirejs optimization page also gives a description of most of the parameters used in the build file, and there is also a super detailed example in the repo. Our basic build file for the sake of this article looks like this:

Here, r.js would be run from the root of the project (containing the app/ folder) like this:

r.js -o build.js

This build file references a Requirejs config file with mainConfigFile; again note that they are two different things. r.js will look in the given config file for any Requirejs config given with requirejs.config. Most importantly, it will grab your paths parameter from there and use those paths to find all of your modules. If you're not using a mainConfigFile parameter in your build file, you can also specify the paths here, but this approach of referencing the config file avoids needing to repeat information.

baseUrl determines the directory for the later include parameter and also for the paths given in the config file.

out gives the output file path relative to where r.js was run.

The optimize parameter here is just telling r.js to minify the code when it concatenates everything, which is nice for your build process but not necessary.

include points to an array of main Requirejs files to include, or just the single main file in our case. Other files specified by paths will still be included without repeating them here. Note that this main file is the same as our mainConfigFile. That's because the this file contains our config as well as the entry point for our app and is used independently for each.

The name parameter is pointing to almond, relative to our baseUrl, which will include almond in the build process.

Keep in mind that r.js is incredibly finicky about these paths and you must get everything perfectly right!

The Result

Running this setup will gather all files in your project, concatenate them, minify them, and output them into the specified output file in a way that can be used by external projects.

However, if you're not using almond, you'll notice that the user of your project still needs to include Requirejs!

Almond

Almond allows you to build to a file without depending on Requirejs. It's a bare bones AMD loader that replaces the minimal needed functionality of Requirejs and sticks itself into your final built file.

If you included almond in the name attribute in your build file as shown above, your output file will be ready to go.

From Here

Requirejs can add a lot of headaches with how finicky it can be, but the benefits of breaking up your JavaScript nicely with AMD are pretty great. Stick to a configuration similar to the above and you should be able to get your setup working smoothly. And don't forget that you can stick the parameters in your build file into the task options for Grunt and use this easily in your build process.