Building a Requirejs Project to a Single, Reusable File
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:
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.
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.
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.
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!
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 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.