sprockets-browserify 0.2.0 → 0.3.0

data/node_modules/browserify/node_modules/url/node_modules/punycode/vendor/requirejs/docs/faq.html

@@ -0,0 +1,8 @@
+<div id="directory" class="section">
+<h1>RequireJS FAQs (Frequently Asked Questions)</h1>
+
+<ul class="index mono">
+<li class="hbox"><a href="faq-optimization.html">Optimization Tool</a><span class="spacer boxFlex"></span><span class="sect">page 1</span></li>
+<li class="hbox"><a href="faq-advanced.html">Advanced Use</a><span class="spacer boxFlex"></span><span class="sect">page 2</span></li>
+</ul>
+</div>

data/node_modules/browserify/node_modules/url/node_modules/punycode/vendor/requirejs/docs/history.html

@@ -0,0 +1,28 @@
+<div id="directory" class="section">
+    <h1>RequireJS History</h1>
+</div>
+
+<div class="section">
+<p><a href="https://github.com/jrburke">I</a> worked a lot on the Dojo Loader. The normal dojo loader used to use synchronous XMLHttpRequest (XHR) calls. However, the XHR loader couldn't load Dojo modules from other domains because of the same-origin restrictions. So I created the xdomain loader that required a build step to inject function wrappers similar to what RequireJS uses, but more complex, due to i18n bundle loading and dojo.requireIf behavior. Because of the more complex i18n and requireIf requirements and the existence of many dojo modules already out in the world, I did not feel like the Dojo community would consider writing modules with function wrappers manually.</p>
+
+<p>However, the sync XHR loader has other issues, like making debugging harder. In 2009, David Mark suggested that Dojo use document.write() to load modules before the page loads to help with that issue, but it meant required dependencies would not load until after the current module executes. This can cause errors if the module references a dependency as part of the module's definition. So a function wrapper was needed. The Dojo community seemed more amenable to considering a function wrapper, particularly since we are considering a Dojo 2.0 that can break some APIs. I fleshed out some of the details for RequireJS (then called RunJS) on the dojo-contributors list, and Mike Wilson originally pushed for a more generic loader that could load plain files as well as allow for different contexts.</p>
+
+<p>YUI 3's use() function is also very similar to require, and use()'s API (but not code) also informed RequireJS' structure. I believe RequireJS is more generic, since YUI seems to use labels for their modules that do not directly correspond to file paths. I also liked explicitly passing the dependent modules as arguments to the function definition, since it allowed linting tools like JSLint to be more effective.</p>
+
+<p>I originally wanted something that would work with CommonJS modules, but those modules seemed to be structured assuming a synchronous module loader, which is possible in server-side JavaScript environments. However, I was mostly concerned with something that worked well in the browser, and that meant needing a function wrapper so we could use script tags. Using synchronous XHR is not very friendly for new developers or people who want ease of debugging across browsers. It can also be slower than plain script tag loading. Some environments, like Adobe AIR do not allow eval() and most developers are taught that eval() is evil and should be avoided.</p>
+
+<p>I created the seeds of RequireJS as RunJS. As I tried to get more in sync with CommonJS modules to allow more code reuse, I proposed <a href="http://wiki.commonjs.org/wiki/Modules/Transport/C">CommonJS Transport/C proposal</a>. The transport format allows mapping traditional CommonJS modules to a format that works best in the browser. I then converted the RunJS code to RequireJS to match the API in the Transport/C proposal.</p>
+
+<p>In the process of implementing the transport format, it became clearer that CommonJS modules allowed an imperative require() usage, which is awkward on the web. Many cases would not work in a web context, and a better solution was to allow for a callback-based require for those cases. However, some of the participants on the CommonJS list wanted to keep the imperative use even in a callback-style require, which made that API more wordy than it should have been.</p>
+
+<p>There was some tuning of the Transport/C proposal, and Kris Zyp figured out how to get anonymous modules to work within that format. At that point, Kris felt like it could function as a module API proposal instead of just a transport format, and he created a proposal on the CommonJS wiki for an Asynchronous Module Definition (AMD) API. During the discussion of that API, Tom Robinson suggested the use of Function.prototype.toString() to scan a factory function for dependencies, although Tom did not care for the AMD API in general. The toString() scanning was incorporated in the AMD API as a simplified CommonJS wrapping, since not all JS environments supported usable toString() values.</p>
+
+<p>Some participants on the CommonJS list that felt the AMD API proposal was not in line with the original CommonJS module goals since it did not keep the full imperative require() style in CommonJS modules. They also felt that proposal was sprung on the list and implemented and evangelized improperly, although from my perspective it was marked as a proposal, and there were other people talking about their implementations of other CommonJS proposals.</p>
+
+<p>There was enough break down in communication that it made it difficult to continue discussing AMD on the CommonJS list. However, there were enough of us web developers that still saw value in it, and there was still some API work to be done around loader plugins and callback-require that the amd-implement email list and amdjs Github group were formed to continue those discussions.</p>
+
+<p>Through the amd-implement list, the callback-require and loader plugin APIs got more definition and a set of unit tests. More AMD implementations were made. Dojo was already in a code conversion process to use AMD, and other people like MooTools and EmbedJS picked it up. AMD loaders gained traction in the jQuery community among those that wanted modular JS loading capabilities.</p>
+
+<p>AMD has a healthy ecosystem around it now. I continue to help push AMD forward by providing a solid implementation in RequireJS, and making sure it fits well with the web.</p>
+
+</div>

data/node_modules/browserify/node_modules/url/node_modules/punycode/vendor/requirejs/docs/jquery.html

@@ -0,0 +1,181 @@
+<div id="directory" class="section">
+<h1>How to use RequireJS with jQuery</h1>
+<ul class="index mono">
+    <li class="hbox">
+        <a href="#get">Get RequireJS</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1</span>
+    </li>
+    <li class="hbox">
+        <a href="#setup">Set up your HTML page</a><span class="spacer boxFlex"></span><span class="sect">&sect; 2</span>
+    </li>
+    <li class="hbox">
+        <a href="#optimize">Feel the need for speed</a><span class="spacer boxFlex"></span><span class="sect">&sect; 3</span>
+    </li>
+    <li class="hbox">
+        <a href="#advanced">Advanced use</a><span class="spacer boxFlex"></span><span class="sect">&sect; 4</span>
+    </li>
+</ul>
+<p>When a project reaches a certain size, managing the script modules for a project starts to get tricky. You need to be sure to sequence the scripts in the right order, and you need to start seriously thinking about combining scripts together into a bundle for deployment, so that only one or a very small number of requests are made to load the scripts.</p>
+
+<p>You may also want to load code on the fly, after page load.</p>
+
+<p>RequireJS can help you manage the script modules, load them in the right order, and make it easy to combine the scripts later via the RequireJS <a href="optimization.md">optimizer</a> without needing to change your markup. It also gives you an easy way to load scripts after the page has loaded, allowing you to spread out the download size over time.</p>
+
+<p>RequireJS has a module system that lets you define well-scoped modules, but you do not have to follow that system to get the benefits of dependency management and build-time optimizations. Over time, if you start to create more modular code that needs to be reused in a few places, the module format for RequireJS makes it easy to write encapsulated code that can be loaded on the fly. It can grow with you, particularly if you want to incorporate internationalization (i18n) string bundles, to localize your project for different languages, or load some HTML strings and make sure those strings are available before executing code, or even use JSONP services as dependencies.</p>
+</div>
+
+<div class="section">
+<h2>
+<a name="get">Get RequireJS</a>
+<span class="sectionMark">&sect; 1</span>
+</h2>
+
+<p>First step is to get RequireJS:</p>
+<ul>
+    <li><a href="download.html#samplejquery">download the sample project</a>.</li>
+</ul>
+
+<p>This sample project uses a combined jQuery+RequireJS file. If you prefer to not bundle jQuery with RequireJS, the <a href="https://github.com/jrburke/require-jquery">sample project's README</a> has an alternate way to use jQuery with RequireJS, but it requires consideration of more edge cases.</p>
+
+</div>
+
+<div class="section">
+<h2>
+<a name="setup">Set up your HTML page</a>
+<span class="sectionMark">&sect; 2</span>
+</h2>
+
+<p>A sample HTML page would look like this (assuming you put all your .js files in a "scripts" subdirectory):</p>
+
+<pre><code>&lt;!DOCTYPE html&gt;
+&lt;html&gt;
+    &lt;head&gt;
+        &lt;title&gt;jQuery+RequireJS Sample Page&lt;/title&gt;
+        &lt;script data-main="scripts/main" src="scripts/require-jquery.js"&gt;&lt;/script&gt;
+    &lt;/head&gt;
+    &lt;body&gt;
+        &lt;h1&gt;jQuery+RequireJS Sample Page&lt;/h1&gt;
+    &lt;/body&gt;
+&lt;/html&gt;
+</code></pre>
+
+<span class="note">The path rules used for data-main changed in RequireJS 0.23. Before that version, data-main="main" for the above example.</span>
+
+<p>The data-main attribute on the script tag for require.js tells RequireJS to load the scripts/main.js file. RequireJS will load any dependency that is passed to require() without a ".js" file from the same directory as the one used for data-main. If you feel more comfortable specifying the whole path, you can also do the following:</p>
+
+<pre><code>&lt;script data-main="scripts/main.js" src="scripts/require-jquery.js"&gt;&lt;/script&gt;
+</code></pre>
+
+<p>What is in main.js? A call to require() to load all the scripts you need and any init work you want to do for the page. This example main.js script loads two plugins, jquery.alpha.js and jquery.beta.js (not the names of real plugins, just an example). The plugins should be in the same directory as require-jquery.js:</p>
+
+<p>main.js:</p>
+
+<pre><code>require(["jquery", "jquery.alpha", "jquery.beta"], function($) {
+    //the jquery.alpha.js and jquery.beta.js plugins have been loaded.
+    $(function() {
+        $('body').alpha().beta();
+    });
+});
+</code></pre>
+
+<p>In the require() call, "jquery" was referenced as a dependency. The require-jquery.js file has special code in it to register jQuery as a RequireJS module, and since it is registered as a module, you can get a handle on that module as the first argument to the function callback passed to require. In the above example, $ is used to reference the jQuery module.</p>
+
+<p>Since jquery.alpha and jquery.beta are just plugins that augment jQuery, they do not return modules that you can reference as function arguments.</p>
+
+</div>
+
+<div class="section">
+<h2>
+<a name="optimize">Feel the need for speed</a>
+<span class="sectionMark">&sect; 3</span>
+</h2>
+
+<p>Now your page is set up to be optimized very easily via the <a href="optimization.html">optimizer</a>.</p>
+
+<p>If you downloaded the jQuery sample project, then the optimizer that is part of the RequireJS source is already included.</p>
+
+<p>If you are not using the jQuery sample project, get the optimizer by downloading the <a href="download.html#rjs">r.js file</a> and place it anywhere you like outside your web development area.</p>
+
+<p>For the purposes of this example, the RequireJS source is placed as a sibling to the <strong>webapp</strong> directory, which contains the HTML page and the scripts directory with all the scripts. Complete directory structure:</p>
+
+<ul>
+<li>r.js  (the file that includes the optimizer)</li>
+<li>webapp/app.html</li>
+<li>webapp/scripts/main.js</li>
+<li>webapp/scripts/require-jquery.js</li>
+<li>webapp/scripts/jquery.alpha.js</li>
+<li>webapp/scripts/jquery.beta.js</li>
+</ul>
+
+<p>Then, in the scripts directory that has require-jquery.js and main.js, create a file called app.build.js with the following contents:</p>
+
+<pre><code>({
+    appDir: "../",
+    baseUrl: "scripts",
+    dir: "../../webapp-build",
+    //Comment out the optimize line if you want
+    //the code minified by UglifyJS.
+    optimize: "none",
+
+    paths: {
+        "jquery": "require-jquery"
+    },
+
+    modules: [
+        {
+            name: "main",
+            exclude: ["jquery"]
+        }
+    ]
+})
+</code></pre>
+
+<p>To use the optimizer, you need <a href="http://nodejs.org">Node</a> or Java 6 installed. These instructions assume Node is being used. See the <a href="optimization.html">Optimization page</a> for more information.</p>
+
+<p>To start the build, go to the <strong>webapp/scripts</strong> directory, execute the following command:</p>
+
+<pre><code>node ../../r.js -o app.build.js
+</code></pre>
+
+<p>Now, in the webapp-build directory, main.js will have the main.js contents, jquery.alpha.js and jquery.beta.js inlined. If you then load the app.html file in the webapp-build directory, you should not see any network requests for jquery.alpha.js and jquery.beta.js.</p>
+</div>
+
+
+<div class="section">
+<h2>
+<a name="advanced">Advanced use</a>
+<span class="sectionMark">&sect; 4</span>
+</h2>
+
+<p>The steps above make it easy start modular development with jQuery, particularly if you are using
+jQuery plugins that assume jQuery is already loaded in the page. The trade-off with the above approach
+is using a combined RequireJS and jQuery file.</p>
+
+<p>Ideally you would not need to include jQuery with RequireJS, and just use RequireJS to load jQuery
+on demand. However, by default scripts can load out of order with RequireJS, and this does not work well
+with jQuery plugins.</p>
+
+<p>Some options:</p>
+
+<ul>
+    <li>Use the <a href="api.html#order">order plugin</a> to load jQuery and the plugins you
+    use in the correct order.</li>
+    <li>Use the priority config to load jQuery before other scripts load. See the
+    <a href="https://github.com/jrburke/require-jquery">Alternate Integration section
+    in the require-jquery project</a> for more information.</li>
+    <li>Wrap the plugins in a define() call.</li>
+</ul>
+
+<p>Ideally all the jQuery plugins you use would optionally call define() to register
+as a module. Some of the plugins you use may already call define() to register as an
+AMD module. If they do not, then you can wrap the code yourself with this wrapper:
+
+<pre><code>define(['jquery'], function ($) {
+    //Plugin code goes here.
+});
+</code></pre>
+
+<p>In addition, you can ask the plugin author to optionally calling define()
+in their code. The <a href="https://github.com/umdjs/umd">umdjs project</a>
+has some resources and examples to help them.</p>
+
+</div>

data/node_modules/browserify/node_modules/url/node_modules/punycode/vendor/requirejs/docs/node.html

@@ -0,0 +1,181 @@
+<div id="directory" class="section">
+<h1>RequireJS in Node</h1>
+
+    <ul class="index mono">
+        <li class="hbox">
+            <a href="#1">Doesn't Node already have a module loader?</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1</span>
+        </li>
+        <li class="hbox">
+            <a href="#2">Can I use server modules written in the CommonJS module format?</a><span class="spacer boxFlex"></span><span class="sect">&sect; 2</span>
+        </li>
+        <li class="hbox">
+            <a href="#3">How do I use it?</a><span class="spacer boxFlex"></span><span class="sect">&sect; 3</span>
+        </li>
+    </ul>
+
+</div>
+
+<div class="section">
+<h2>
+<a name="1">Doesn't Node already have a module loader?</a>
+<span class="sectionMark">&sect; 1</span>
+</h2>
+
+<p>Yes <a href="http://nodejs.org">Node</a> does. That loader uses the CommonJS module format. The CommonJS module format is <a href="why.html">non-optimal for the browser</a>, and I do not agree with <a href="http://tagneto.blogspot.com/2010/03/commonjs-module-trade-offs.html">some of the trade-offs made in the CommonJS module format</a>. By using RequireJS on the server, you can use one format for all your modules, whether they are running server side or in the browser. That way you can preserve the speed benefits and easy debugging you get with RequireJS in the browser, and not have to worry about extra translation costs for moving between two formats.</p>
+
+<p>If you want to use define() for your modules but still run them in Node without needing to run RequireJS on the server, see <a href="#nodeModules">the section below</a> about using <a href="https://github.com/jrburke/amdefine">amdefine</a>.</p>
+
+</div>
+
+<div class="section">
+<h2>
+<a name="2">Can I use Node modules already written in the CommonJS module format?</a>
+<span class="sectionMark">&sect; 2</span></h2>
+
+<p>Yes! The Node adapter for RequireJS, called r.js, will use Node's implementation of require and Node's search paths if the module is not found with the configuration used by RequireJS, so you can continue to use your existing Node-based modules without having to do changes to them.</p>
+
+<p>RequireJS will use its <a href="api.html#config">Configuration Options</a> first to find modules. If RequireJS cannot find the module with its configuration, it is assumed to be a module that uses Node's type of modules and configuration. So, only configure module locations with RequireJS if they use the RequireJS API. For modules that expect Node's APIs and configuration/paths, just install them with a Node package manager, like <a href="http://npmjs.org/">npm</a>, and do not configure their locations with RequireJS.</p>
+
+<p><strong>Best practice</strong>: Use npm to install Node-only packages/modules into the projects <strong>node_modules</strong> directory, but do not configure RequireJS to look inside the node_modules directory. Also avoid using relative module IDs to reference modules that are Node-only modules. So, <strong>do not</strong> do something like <strong>require("./node_modules/foo/foo")</strong>.</p>
+
+<p>Even though RequireJS is an asynchronous loader in the browser, the RequireJS Node adapter loads modules synchronously in the Node environment to match the default loading behavior in Node.</p>
+
+<p>Finally, RequireJS in Node can only load modules that are on the local disk -- fetching modules across http, for instance, is not supported at this time.</p>
+
+</div>
+
+<div class="section">
+<h2>
+<a name="3">How do I use it?</a>
+<span class="sectionMark">&sect; 3</span>
+</h2>
+
+<p>There are two ways to get the Node adapter:</p>
+
+<h3 id="npm">npm</h3>
+<p>Use <a href="http://npmjs.org">npm</a> to install it:</p>
+
+<pre><code>npm install requirejs
+</code></pre>
+
+<p>This option will install the latest release.</p>
+
+<h3 id="rjs">Download r.js</h3>
+
+<p>If you prefer to not use npm, you can get r.js directly:</p>
+
+<ul>
+    <li>Download r.js from the <a href="download.html#rjs">the download page</a> and place it in your project.</li>
+    <li>Get the source from the <a href="https://github.com/jrburke/r.js">r.js repo</a> and either generate the r.js via "node dist.js", or grab a snapshot from the <strong>dist</strong> directory.</li>
+</ul>
+
+<h3 id="usage">Usage<h3>
+
+<p>These instructions assume an npm installation of 'requirejs'. If you are using the r.js file directly, replace  require('requirejs') with require('./path/to/r.js'). Basic usage is:</p>
+
+<ul>
+    <li>require('requirejs')</li>
+    <li>Pass the main js file's "require" function in the configuration to requirejs.</li>
+</ul>
+
+<p>Example:</p>
+
+<pre><code>var requirejs = require('requirejs');
+
+requirejs.config({
+    //Pass the top-level main.js/index.js require
+    //function to requirejs so that node modules
+    //are loaded relative to the top-level JS file.
+    nodeRequire: require
+});
+
+requirejs(['foo', 'bar'],
+function   (foo,   bar) {
+    //foo and bar are loaded according to requirejs
+    //config, but if not found, then node's require
+    //is used to load the module.
+});
+</code></pre>
+
+<p>Be sure to read the <a href="#2">notes in section 2</a> about configuring RequireJS so that it can load node-only modules installed via npm.</p>
+
+<p>To see a more complete example that loads a module via RequireJS but uses Node-native modules for other things, see the <a href="https://github.com/jrburke/r.js/tree/master/tests/node/embedded">embedded test</a> in the r.js repo.</p>
+
+<h3 id="nodeModules">Building node modules with AMD or RequireJS</h3>
+
+<p>If you want to code a module so that it works with RequireJS and in Node, without requiring users of your library in Node to use RequireJS, then you can use the <a href="https://github.com/jrburke/amdefine">amdefine</a> package to do this:</p>
+
+<pre><code>if (typeof define !== 'function') {
+    var define = require('amdefine')(module);
+}
+
+define(function(require) {
+    var dep = require('dependency');
+
+    //The value returned from the function is
+    //used as the module export visible to Node.
+    return function () {};
+});
+</code></pre>
+
+<p>The RequireJS optimizer, as of version 1.0.3, will strip out the use of 'amdefine' above, so it is safe to use this module for your web-based projects too. Just be sure to use <strong>the exact 'amdefine' if() test and contents as shown above</strong>. Differences in spaces/line breaks are allowed. See the <a href="https://github.com/jrburke/amdefine">amdefine project</a> for more information.</p>
+
+<p>If you want to use RequireJS directly to code your module, and then export a module value to node so that it can be used in other Node programs without requiring that app to use RequireJS, you can use the code mentioned above in the <a href="#usage">basic usage section</a> with a few modifications.</p>
+
+<p>It is best to set the baseUrl specifically to the directory containing the module, so that it works properly when nested inside a node_modules heirarchy. Then use Node's module.exports to export your module value:</p>
+
+<pre><code>var requirejs = require('requirejs');
+
+requirejs.config({
+    //Use node's special variable __dirname to
+    //get the directory containing this file.
+    //Useful if building a library that will
+    //be used in node but does not require the
+    //use of node outside
+    baseUrl: __dirname,
+
+    //Pass the top-level main.js/index.js require
+    //function to requirejs so that node modules
+    //are loaded relative to the top-level JS file.
+    nodeRequire: require
+});
+
+requirejs(['foo', 'bar'],
+function   (foo,   bar) {
+    //foo and bar are loaded according to requirejs
+    //config, but if not found, then node's require
+    //is used to load the module.
+
+    //Now export a value visible to Node.
+    module.exports = function () {};
+});
+</code></pre>
+
+<h3 id="optimizer">Using the optimizer as a node module</h3>
+
+<p>The node module also exposes the RequireJS Optimizer as an <strong>optimize</strong> method for using the <a href="optimization.html">RequireJS optimizer</a> via a function call instead of a command line tool:</p>
+
+<pre><code>var requirejs = require('requirejs');
+
+var config = {
+    baseUrl: '../appDir/scripts',
+    name: 'main',
+    out: '../build/main-built.js'
+};
+
+requirejs.optimize(config, function (buildResponse) {
+    //buildResponse is just a text output of the modules
+    //included. Load the built file for the contents.
+    //Use config.out to get the optimized file contents.
+    var contents = fs.readFileSync(config.out, 'utf8');
+});
+</code></pre>
+
+<p>This allows you to build other optimization workflows, like <a href="https://github.com/jrburke/r.js/tree/master/build/tests/http">a web builder</a> that can be used if you prefer to always develop with the "one script file included before the &lt;/body&gt; tag" approach. The optimizer running in Node if fairly fast, but for larger projects that do not want to regenerate the build for every browser request, but just if you modify a script that is part of the build. You could use Node's fs.watchFile() to watch files and then trigger the build when a file changes.</p>
+
+<h3 id="feedback">Feedback</h3>
+
+<p>If you find you have a problem, and want to report it, use the <a href="http://github.com/jrburke/r.js/issues">r.js GitHub Issues page</a>.</p>
+
+<p>If you want to discuss the RequireJS-Node integration, you can use the <a href="http://groups.google.com/group/requirejs">RequireJS Group</a>.</p>
+</div>

data/node_modules/browserify/node_modules/url/node_modules/punycode/vendor/requirejs/docs/optimization.html

@@ -0,0 +1,420 @@
+<div id="directory" class="section">
+<h1>RequireJS Optimizer</h1>
+
+<ul class="index mono">
+<li class="hbox"><a href="#requirements">Requirements</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1</span></li>
+<li class="hbox"><a href="#download">Download</a><span class="spacer boxFlex"></span><span class="sect">&sect; 2</span></li>
+<li class="hbox"><a href="#setup">Example setup</a><span class="spacer boxFlex"></span><span class="sect">&sect; 3</span></li>
+<li class="hbox"><a href="#onejs">Optimizing one JavaScript file</a><span class="spacer boxFlex"></span><span class="sect">&sect; 4</span></li>
+<li class="hbox"><a href="#shallow">Shallow exclusions for fast development</a><span class="spacer boxFlex"></span><span class="sect">&sect; 5</span></li>
+<li class="hbox"><a href="#empty">empty: paths for network/CDN resources</a><span class="spacer boxFlex"></span><span class="sect">&sect; 6</span></li>
+<li class="hbox"><a href="#onecss">Optimizing one CSS file</a><span class="spacer boxFlex"></span><span class="sect">&sect; 7</span></li>
+<li class="hbox"><a href="#wholeproject">Optimizing a whole project</a><span class="spacer boxFlex"></span><span class="sect">&sect; 8</span></li>
+<li class="hbox"><a href="#hasjs">Integration with has.js</a><span class="spacer boxFlex"></span><span class="sect">&sect; 9</span></li>
+<li class="hbox"><a href="#options">All configuration options</a><span class="spacer boxFlex"></span><span class="sect">&sect; 10</span></li>
+<li class="hbox"><a href="#pitfalls">Common pitfalls</a><span class="spacer boxFlex"></span><span class="sect">&sect; 11</span></li>
+</ul>
+
+<p>RequireJS has an optimization tool that does the following</p>
+
+<ul class="serif">
+<li>Combines related scripts together into build layers and minifies them via <a href="https://github.com/mishoo/UglifyJS">UglifyJS</a>  (the default) or <a href="http://code.google.com/closure/compiler/">Closure Compiler</a> (an option when using Java).</li>
+<li>Optimizes CSS by inlining CSS files referenced by @import and removing comments.</li>
+</ul>
+
+<p>The optimizer is part of the <a href="https://github.com/jrburke/r.js">r.js adapter for Node and Rhino</a>, 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.</p>
+
+<p>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 <a href="whyamd.html#sugar">simplified CommonJS wrapping</a>. So, it will not find modules that are loaded via a variable name:</p>
+
+<pre><code>var mods = someCondition ? ['a', 'b'], ['c', 'd'];
+require(mods);</code></pre>
+
+<p>but 'a' and 'b' will be included if specified like so:</p>
+
+<pre><code>require(['a', 'b']);</code></pre>
+
+<p>or:</p>
+
+<pre><code>define(['a', 'b'], function (a, b) {});</code></pre>
+
+<p>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 <strong>include</strong> option.</p>
+
+</div>
+
+<div class="section">
+<h2>
+<a href="#requirements" name="requirements">Requirements</a>
+<span class="sectionMark">&sect; 1</span>
+</h2>
+
+<p>The optimizer can be run using either Node or using Java with Rhino. The requirements for each option:<p>
+
+<ul>
+   <li><strong>Node:</strong> (preferred) <a href="http://nodejs.org">Node</a> 0.4.0 or later.</li>
+   <li><strong>Java:</strong> <a href="http://java.com/">Java 1.6</a> or later.</li>
+</ul>
+
+<p>Node is the preferred execution environment. The optimizer runs <strong>much faster</strong> with Node.</p>
+
+<p>All the example commands in this page assume Node usage, and running on a Linux/OS X command line. See the <a href="https://github.com/jrburke/r.js">r.js README</a> for how to run it in Java.</p>
+
+</div>
+
+<div class="section">
+<h2><a href="#download" name="download">Download</a><span class="sectionMark">&sect; 2</span></h2>
+
+<p>1) You can download the tool on <a href="download.html#rjs">the download page</a>.</p>
+
+<p>2) If you are using Node with NPM, you can install r.js as part of the "requirejs" package in NPM:</p>
+
+<pre><code>&gt; npm install requirejs
+&gt; r.js -o app.build.js
+</code></pre>
+
+<p>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:</p>
+
+<pre><code>&gt; npm install -g requirejs
+</code></pre>
+
+<p>If you install the requirejs npm package, you can also <a href="node.html#optimizer">use the optimizer via a function call</a> inside a node program.</p>
+
+<p>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.</p>
+
+</div>
+
+<div class="section">
+<h2><a href="#setup" name="setup">Example setup</a><span class="sectionMark">&sect; 3</span></h2>
+
+<p>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.</p>
+
+<p>Example setup:</p>
+
+<ul>
+<li>appdirectory
+<ul>
+<li>main.html</li>
+<li>css
+<ul>
+<li>common.css</li>
+<li>main.css</li>
+</ul></li>
+<li>scripts
+<ul>
+<li>require.js</li>
+<li>main.js</li>
+<li>one.js</li>
+<li>two.js</li>
+<li>three.js</li>
+</ul></li>
+</ul></li>
+<li>r.js (The r.js optimizer from <a href="download.html#rjs">download page</a>)</li>
+</ul>
+
+<p>main.html has script tags for require.js and loads main.js via a require call, like so:</p>
+
+<pre><code>&lt;!DOCTYPE html&gt;
+&lt;html&gt;
+    &lt;head&gt;
+        &lt;title&gt;My App&lt;/title&gt;
+        &lt;link rel="stylesheet" type="text/css" href="css/main.css"&gt;
+        &lt;script data-main="scripts/main" src="scripts/require.js"&gt;&lt;/script&gt;
+    &lt;/head&gt;
+    &lt;body&gt;
+        &lt;h1&gt;My App&lt;/h1&gt;
+    &lt;/body&gt;
+&lt;/html&gt;
+</code></pre>
+
+<p>main.js loads one.js, two.js and three.js via a require call:</p>
+
+<pre><code>require(["one", "two", "three"], function (one, two, three) {
+});
+</code></pre>
+
+<p>main.css has content like the following:</p>
+
+<pre><code>@import url("common.css");
+
+.app {
+    background: transparent url(../../img/app.png);
+}
+</code></pre>
+</div>
+
+<div class="section">
+<h2>
+<a href="#onejs" name="onejs">Optimizing one JavaScript file</a>
+<span class="sectionMark">&sect; 4</span>
+</h2>
+
+<p>Use the above example setup, if you just wanted to optimize main.js, you could use this command, from inside the <strong>appdirectory/scripts</strong> directory:</p>
+
+<pre><code>node ../../r.js -o name=main out=main-built.js baseUrl=.
+</code></pre>
+
+<p>This will create a file called <strong>appdirectory/scripts/main-built.js</strong> that will include the contents of main.js, one.js, two.js and three.js.</p>
+
+<p>Normally you should <strong>not</strong> 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 <strong>out=</strong> 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.</p>
+
+<p>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:</p>
+
+<pre><code>node ../../r.js -o baseUrl=. paths.requireLib=../../require name=main include=requireLib out=main-built.js
+</code></pre>
+
+<p>Since "require" is a reserved dependency name, you create a "requireLib" dependency and map it to the require.js file.</p>
+
+<p>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.</p>
+
+<p>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 <a href="faq-optimization.html">Optimization FAQ</a>.</p>
+</div>
+
+<div class="section">
+<h2><a href="#shallow" name="shallow">Shallow exclusions for fast development</a><span class="sectionMark">&sect; 5</span> </h2>
+
+<p>You can use the <a href="#onejs">one JavaScript file optimization</a> 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.</p>
+
+<p>You can do this by using the <strong>excludeShallow</strong> option. Using the <a href="#example">example setup</a> above, assume you are currently building out or debugging two.js. You could use this optimization command:</p>
+
+<pre><code>node ../../r.js -o name=main excludeShallow=two out=main-built.js baseUrl=.
+</code></pre>
+
+<p>If you do not want the main-build.js file minified, pass <strong>optimize=none</strong> in the command above.</p>
+
+<p>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":</p>
+
+<pre><code>&lt;!DOCTYPE html&gt;
+&lt;html&gt;
+    &lt;head&gt;
+        &lt;title&gt;My App&lt;/title&gt;
+        &lt;link rel="stylesheet" type="text/css" href="css/main.css"&gt;
+        &lt;script src="scripts/require.js"&gt;&lt;/script&gt;
+        &lt;script&gt;
+            require.config({
+                paths: {
+                    //Comment out this line to go back to loading
+                    //the non-optimized main.js source file.
+                    "main": "main-built"
+                }
+            });
+            require(["main"]);
+        &lt;/script&gt;
+    &lt;/head&gt;
+    &lt;body&gt;
+        &lt;h1&gt;My App&lt;/h1&gt;
+    &lt;/body&gt;
+&lt;/html&gt;
+</code></pre>
+
+<p>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.</p>
+</div>
+
+<div class="section">
+<h2><a href="#empty" name="empty">empty: paths for network/CDN resources</a><span class="sectionMark">&sect; 6</span></h2>
+
+<p>You may have a script you want to load from a <a href="http://en.wikipedia.org/wiki/Content_delivery_network">Content Delivery Network (CDN)</a> or any other server on a different domain.</p>
+
+<p>The optimizer cannot load network resources, so if you want it included in the build, be sure to create a <a href="api.html#config-paths">paths config</a> to map the file to a module name. Then, for running the optimizer, download the CDN script and pass a paths config to the optimizer that maps the module name to the local file path.</p>
+
+<p>However, it is more likely that you do not want to include that resource in the build. If the script does not have any dependencies, or you do not want to include its dependencies or will be including them in another way, then you can use the special <strong>'empty:' scheme</strong> in the paths config to just skip the file when doing an optimization.</p>
+
+<p>In your main.js file, create a paths config that gives the script a module name. This can be done even if the script does not define a module via a call to define(). paths config are just used to map short module/script IDs to an URL. This allows you to use a a different paths config for the optimization. In main.js:</p>
+
+<pre><code>requirejs.config({
+    paths: {
+        'jquery': 'https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min'
+    }
+});
+
+require(['jquery'], function ($) {
+});
+</code></pre>
+
+<p>Then, when running the optimizer, use 'empty:' for the paths config:</p>
+
+<pre><code>node ../../r.js -o name=main out=main-built.js baseUrl=. paths.jquery=empty:
+</code></pre>
+
+<p>Or, in a <a href="#wholeproject">build profile</a>:</p>
+
+<pre><code>({
+    baseUrl: ".",
+    name: "main",
+    out: "main-built.js",
+    paths: {
+        jquery: "empty:"
+    }
+})
+</code></pre>
+
+</div>
+
+
+<div class="section">
+<h2><a href="#onecss" name="onecss">Optimizing one CSS file</a><span class="sectionMark">&sect; 7</span></h2>
+
+<p>Use the above example setup, if you just wanted to optimize main.css, you could use this command, from inside the <strong>appdirectory/css</strong> directory:</p>
+
+<pre><code>node ../../r.js -o cssIn=main.css out=main-built.css
+</code></pre>
+
+<p>This will create a file called <strong>appdirectory/css/main-build.css</strong> that will include the contents of common.js, have the url() paths properly adjusted, and have comments removed.</p>
+
+<p>See the notes for the <a href="#onejs">Optimizing one JavaScript file</a> about avoiding saving optimized files in your pristine source tree. It is only done here to make the example simpler.</p>
+
+<span class="note">Note: The url() path fixing will always fix the paths relative to the <strong>cssIn</strong> build option path, not the <strong>out</strong> build option.</span>
+</div>
+
+<div class="section">
+<h2><a href="#wholeproject" name="wholeproject">Optimizing a whole project</a><span class="sectionMark">&sect; 8</span></h2>
+
+<p>The optimizer can take care of optimizing all the CSS and JS files in your project by using a build profile.</p>
+
+<p>Create a build profile, call it app.build.js, and put it in the <strong>scripts</strong> 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:</p>
+
+<pre><code>({
+    appDir: "../",
+    baseUrl: "scripts",
+    dir: "../../appdirectory-build",
+    modules: [
+        {
+            name: "main"
+        }
+    ]
+})
+</code></pre>
+
+<p>This build profile tells RequireJS to copy all of <strong>appdirectory</strong> to a sibling directory called <strong>appdirectory-build</strong> and apply all the optimizations in the <strong>appdirectory-build</strong> 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.</p>
+
+<p>RequireJS will use <strong>baseUrl</strong> to resolve the paths for any module names. The <strong>baseUrl</strong> should be relative to <strong>appDir</strong>.</p>
+
+<p>In the <strong>modules</strong> array, specify the module names that you want to optimize, in the example, "main". "main" will be mapped to <strong>appdirectory/scripts/main.js</strong> in your project. The build system will then trace the dependencies for main.js and inject them into the <strong>appdirectory-build/scripts/main.js</strong> file.</p>
+
+<p>It will also optimize any CSS files it finds inside <strong>appdirectory-build</strong>.</p>
+
+<p>To run the build, run this command from inside the <strong>appdirectory/scripts</strong> directory:</p>
+
+<pre><code>node ../../r.js -o app.build.js
+</code></pre>
+
+<p>Once the build is done, you can use <strong>appdirectory-build</strong> as your optimized project, ready for deployment.</p>
+</div>
+
+<div class="section">
+<h2><a href="#hasjs" name="hasjs">Integration with has.js</a><span class="sectionMark">&sect; 9</span></h2>
+
+<p><a href="https://github.com/phiggins42/has.js">has.js</a> 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.</p>
+
+<p>If your code uses tests like the following:</p>
+
+<pre><code>
+if (has("someThing")) {
+    //use native someThing
+} else {
+    //do some workaround
+}
+</code></pre>
+
+<p>You can define a <b>has</b> 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.</p>
+
+<p>If your build profile looked like so:</p>
+
+<pre><code>
+({
+    baseUrl: ".",
+    name: "hasTestModule",
+    out: "builds/hasTestModule.js",
+    has: {
+        someThing: true
+    }
+})
+</code></pre>
+
+<p>Then the optimizer will transform the above code sample to:</p>
+
+<pre><code>
+if (true) {
+    //use native someThing
+} else {
+    //do some workaround
+}
+</code></pre>
+
+<p>Then, if you use the default optimize setting of "uglify" in r.js 0.26.0 or later, or if the <b>optimize</b> setting is set to "closure" (when <a href="https://github.com/jrburke/r.js">run under Java</a>), 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.</p>
+
+</div>
+
+<div class="section">
+<h2><a href="#options" name="options">All configuration options</a><span class="sectionMark">&sect; 10</span></h2>
+
+<p>There is an <a href="https://github.com/jrburke/r.js/blob/master/build/example.build.js">example.build.js</a> file in the requirejs/build directory that details all of the allowed optimizer configuration options.</p>
+</div>
+
+<div class="section">
+<h2><a href="#pitfalls" name="pitfalls">Common pitfalls</a><span class="sectionMark">&sect; 11</span></h2>
+
+<p>If you are having trouble with the examples below, here are some common pitfalls that might be the source of the problem:</p>
+
+<p><strong>Command line arguments are interchangeable with a build profile properties</strong></p>
+
+<p>You can either specify options on the command line:</p>
+
+<pre><code>node r.js -o baseUrl=. paths.jquery=some/other/jquery name=main out=main-built.js
+</code></pre>
+
+<p>or in a build profile. In a <strong>build.js</strong>, the same command line arguments can be specified like so:</p>
+
+<pre><code>({
+    baseUrl: ".",
+    paths: {
+        jquery: "some/other/jquery"
+    }
+    name: "main",
+    out: "main-built.js"
+})
+</code></pre>
+
+<p>then just pass the build profile's file name to the optimizer:</p>
+
+<pre><code>node r.js -o build.js
+</code></pre>
+
+<p>Command line arguments take precedence over build profile settings, and you can mix them together:</p>
+
+<pre><code>node r.js -o build.js optimize=none
+</code></pre>
+
+<p><strong>Config settings in your main JS file are not read by default by the optimizer</strong></p>
+
+<p>This is because the config settings for a build can be very different, with multiple optimization targets. So a separate set of config options need to be specified for the optimizer.</p>
+
+<p>In version 1.0.5+ of the optimizer, there is now a <strong><a href="https://github.com/jrburke/r.js/blob/master/build/example.build.js#L27">mainConfigFile</a></strong> option. If specified with the path to your main JS file, the first <code>requirejs({}), requirejs.config({}), require({}), or require.config({})</code> found in that file will be parsed out and used as part of the configuration options passed to the optimizer:</p>
+
+<pre><code>mainConfigFile: 'path/to/main.js'
+</code></pre>
+
+<p>The precedence for config: command line, build profile, mainConfigFile. In other words, the mainConfigFile configuration has the lowest priority.</p>
+
+<p><strong>Do not specify the output directory to within the source area for your JavaScript</strong></p>
+
+<p>For instance, if your baseUrl is 'js' and your build output goes into 'js/build', there will likely be problems with extra, nested files generated on each optimization run. This guidance is only for optimizations that are not single file optimizations.</p>
+
+<p><strong>Avoid optimization names that are outside the baseUrl</strong></p>
+
+<p>For instance, if your baseUrl is 'js', and your optimization targets:</p>
+
+<pre><code>name: '../main'</code></pre>
+
+<p>the optimization could overwrite or place files outside the output directory. For those cases, create a <strong>paths</strong> config to map that file to a local name, like:</p>
+
+<pre><code>paths: {
+    main: '../main'
+}
+</code></pre>
+
+<p>then use name:</p>
+
+<pre><code>name: 'main'</code></pre>
+
+<p>for the optimization target.</p>
+
+</div>