# RequireJS Optimizer

- Requirements§ 1
- Download§ 2
- Example Setup§ 3
- Optimizing one JavaScript file§ 4
- Shallow exclusions for fast development§ 5
- Optimizing one CSS file§ 6
- Optimizing a whole project§ 7
- Integration with has.js§ 8
- All configuration options§ 9

RequireJS has an optimization tool that does the following

- Combines related scripts together into build layers and minifies them via UglifyJS (the default) or Closure Compiler (an option when using Java).
- Optimizes CSS by inlining CSS files referenced by @import and removing comments.

The optimizer is part of the r.js adapter for Node and Rhino, and it is designed to be run as part of a build or packaging step after you are done with development and are ready to deploy the code for your users.

The optimizer will only combine modules that are specified in arrays of string literals that are passed to top-level require and define calls, or the require('name') string literal calls in a simplified CommonJS wrapping. So, it will not find modules that are loaded via a variable name:

    var mods = someCondition ? ['a', 'b'], ['c', 'd'];
    require(mods);

but 'a' and 'b' will be included if specified like so:

    require(['a', 'b']);

or:

    define(['a', 'b'], function (a, b) {});

This behavior allows dynamic loading of modules even after optimization. You can always explicitly add modules that are not found via the optimizer's static analysis by using the include option.

## Requirements § 1

The optimizer can be run using either Node or using Java with Rhino. The requirements for each option:

- Node: (preferred) Node 0.4.0 or later.
- Java: Java 1.6 or later.

Node is the preferred execution environment. The optimizer runs much faster with Node.

All the example commands in this page assume Node usage, and running on a Linux/OS X command line. See the r.js README for how to run it in Java.

## Download§ 2

1) You can download the tool on the download page.

2) If you are using Node with NPM, you can install r.js as part of the "requirejs" package in NPM:

    > npm install requirejs
    > r.js -o app.build.js

That will work for a project based in in the directory in which "npm install" is run. You can also install it globally via the -g option to npm:

    > npm install -g requirejs

If you install the requirejs npm package, you can also use the optimizer via a function call inside a node program.

The rest of this page assumes that r.js is just downloaded manually from the download page. It is normally the clearest, most portable way to use the optimizer.

## Example Setup§ 3

The examples in this page will assume you downloaded and saved r.js in a directory that is a sibling to your project directory. The optimizer that is part of r.js can live anywhere you want, but you will likely need to adjust the paths accordingly in these examples.

Example setup:

- appdirectory
  - main.html
  - css
    - common.css
    - main.css
  - scripts
    - require.js
    - main.js
    - one.js
    - two.js
    - three.js
- r.js (The r.js optimizer from download page)

main.html has script tags for require.js and loads main.js via a require call, like so:

    <!DOCTYPE html>
    <html>
        <head>
            <title>My App</title>
            <link rel="stylesheet" type="text/css" href="css/main.css">
            <script data-main="scripts/main" src="scripts/require.js"></script>
        </head>
        <body>
            <h1>My App</h1>
        </body>
    </html>

main.js loads one.js, two.js and three.js via a require call:

    require(["one", "two", "three"], function (one, two, three) {
    });

main.css has content like the following:

    @import url("common.css");

    .app {
        background: transparent url(../../img/app.png);
    }

## Optimizing one JavaScript file § 4

Use the above example setup, if you just wanted to optimize main.js, you could use this command, from inside the appdirectory/scripts directory:

    node ../../r.js -o name=main out=main-built.js baseUrl=.

This will create a file called appdirectory/scripts/main-built.js that will include the contents of main.js, one.js, two.js and three.js.

Normally you should not save optimized files with your pristine project source. Normally you would save them to a copy of your project, but to make this example easier it is saved with the source. Change the out= option to any directory you like, that has a copy of your source. Then, you can change the main-built.js file name to just main.js so the HTML page will load the optimized version of the file.

It is not recommended that you bundle require.js with your main.js file. Ideally require.js should be the same file contents wherever it is used. However, if you do need to include require.js with the main.js source, you can use this command:

    node ../../r.js -o baseUrl=. paths.requireLib=../../require name=main include=requireLib out=main-built.js

Since "require" is a reserved dependency name, you create a "requireLib" dependency and map it to the require.js file.

Once that optimization is done, you can then rename the main-built.js file to require.js and your optimized project will only need to make one script request.

If you want to wrap your built file so it can be used in pages that do not have an AMD loader like RequireJS, see the Optimization FAQ.

## Shallow exclusions for fast development§ 5

You can use the one JavaScript file optimization approach to make your development experience faster. By optimizing all the modules in your project into one file, except the one you are currently developing, you can reload your project quickly in the browser, but still give you the option of fine grained debugging in a module.

You can do this by using the excludeShallow option. Using the example setup above, assume you are currently building out or debugging two.js. You could use this optimization command:

    node ../../r.js -o name=main excludeShallow=two out=main-built.js baseUrl=.

If you do not want the main-build.js file minified, pass optimize=none in the command above.

Then configure the HTML page to load the main-built.js file instead of main.js by configuring the path used for "main" to be "main-built":

    <!DOCTYPE html>
    <html>
        <head>
            <title>My App</title>
            <link rel="stylesheet" type="text/css" href="css/main.css">
            <script src="scripts/require.js"></script>
            <script>
                require.config({
                    paths: {
                        //Comment out this line to go back to loading
                        //the non-optimized main.js source file.
                        "main": "main-built"
                    }
                });
                require(["main"]);
            </script>
        </head>
        <body>
            <h1>My App</h1>
        </body>
    </html>

Now, when this page is loaded, the require() for "main" will load the main-built.js file. Since excludeShallow told it just to exclude two.js, two.js will still be loaded as a separate file, allowing you to see it as a separate file in the browser's debugger, so you can set breakpoints and better track its individual changes.

## Optimizing one CSS file§ 6

Use the above example setup, if you just wanted to optimize main.css, you could use this command, from inside the appdirectory/css directory:

    node ../../r.js -o cssIn=main.css out=main-built.css

This will create a file called appdirectory/css/main-build.css that will include the contents of common.js, have the url() paths properly adjusted, and have comments removed.

See the notes for the Optimizing one JavaScript file about avoiding saving optimized files in your pristine source tree. It is only done here to make the example simpler.

Note: The url() path fixing will always fix the paths relative to the cssIn build option path, not the out build option.

## Optimizing a whole project§ 7

The optimizer can take care of optimizing all the CSS and JS files in your project by using a build profile.

Create a build profile, call it app.build.js, and put it in the scripts directory. The app.build.js file can live anywhere, but just be sure to adjust the paths accordingly in the example below -- all paths will be relative to where the app.build.js is located. Example app.build.js:

    ({
        appDir: "../",
        baseUrl: "scripts",
        dir: "../../appdirectory-build",
        modules: [
            {
                name: "main"
            }
        ]
    })

This build profile tells RequireJS to copy all of appdirectory to a sibling directory called appdirectory-build and apply all the optimizations in the appdirectory-build directory. It is strongly suggested you use a different output directory than the source directory -- otherwise bad things will likely happen as the optimizer overwrites your source.

RequireJS will use baseUrl to resolve the paths for any module names. The baseUrl should be relative to appDir.

In the modules array, specify the module names that you want to optimize, in the example, "main". "main" will be mapped to appdirectory/scripts/main.js in your project. The build system will then trace the dependencies for main.js and inject them into the appdirectory-build/scripts/main.js file.

It will also optimize any CSS files it finds inside appdirectory-build.

To run the build, run this command from inside the appdirectory/scripts directory:

    node ../../r.js -o app.build.js

Once the build is done, you can use appdirectory-build as your optimized project, ready for deployment.

## Integration with has.js§ 8

has.js is a great tool to that adds easy feature detection for your project. There is some optimizer support for optimizing code paths for has.js tests.

If your code uses tests like the following:

    if (has("someThing")) {
        //use native someThing
    } else {
        //do some workaround
    }

You can define a has object in the build config with true or false values for some has() tests, and the optimizer will replace the has() test with the true or false value.

If your build profile looked like so:

    ({
        baseUrl: ".",
        name: "hasTestModule",
        out: "builds/hasTestModule.js",
        has: {
            someThing: true
        }
    })

Then the optimizer will transform the above code sample to:

    if (true) {
        //use native someThing
    } else {
        //do some workaround
    }

Then, if you use the default optimize setting of "uglify" in r.js 0.26.0 or later, or if the optimize setting is set to "closure" (when run under Java), the minifier will optimize out the dead code branch! So you can do custom builds of your code that are optimized for a set of has() tests.

## All configuration options§ 9

There is an example.build.js file in the requirejs/build directory that details all of the allowed optimizer configuration options.