web-apps/vendor/requirejs/docs/commonjs.html

<div id="directory" class="section">
<h1>CommonJS Notes</h1>

<ul class="index mono">
<li class="hbox"><a href="#intro">Introduction</a><span class="spacer boxFlex"></span><span class="sect">&sect; 1</span></li>
<li class="hbox"><a href="#manualconversion">Manual Conversion</a><span class="spacer boxFlex"></span><span class="sect">&sect; 2</span></li>
<li class="hbox"><a href="#autoconversion">Conversion Tool</a><span class="spacer boxFlex"></span><span class="sect">&sect; 3</span></li>
<li class="hbox"><a href="#exports">Setting Exported Value</a><span class="spacer boxFlex"></span><span class="sect">&sect; 4</span></li>
<li class="hbox"><a href="#altsyntax">Alternative Syntax</a><span class="spacer boxFlex"></span><span class="sect">&sect; 5</span></li>
<li class="hbox"><a href="#packages">Loading Modules from CommonJS Packages</a><span class="spacer boxFlex"></span><span class="sect">&sect; 6</span></li>
<li class="hbox"><a href="#optimize">Optimization Tool</a><span class="spacer boxFlex"></span><span class="sect">&sect; 7</span></li>
</ul>

</div>

<div class="section">
<h2><a name="intro">Introduction</a><span class="sectionMark">&sect; 1</span></h2>

<p><a href="http://www.commonjs.org/">CommonJS</a> defines <a href="http://wiki.commonjs.org/wiki/Modules/1.1.1">a module format</a>. Unfortunately, it was defined without giving browsers equal footing to other JavaScript environments. Because of that, there are CommonJS spec proposals for <a href="http://wiki.commonjs.org/wiki/Modules/Transport">Transport formats</a> and an <a href="http://wiki.commonjs.org/wiki/Modules/Async/A">asynchronous require</a>.</p>

<p>RequireJS tries to keep with the spirit of CommonJS, with using string names to refer to dependencies, and to avoid modules defining global objects, but still allow coding a module format that works well natively in the browser. RequireJS implements the <a href="http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition">Asynchronous Module Definition</a> (formerly Transport/C) proposal.</p>

<p>If you have modules that are in the traditional CommonJS module format, then you can easily convert them to work with RequireJS. Not all modules will convert cleanly to the new format. Types of modules that may not convert well:</p>

<ul>
    <li>Modules that use conditional code to do a require call, like if(someCondition) require('a1') else require('a2');</li>
    <li>Some types of circular dependencies.</li>
</div>

<div class="section">
<h2><a name="manualconversion">Manual Conversion</a><span class="sectionMark">&sect; 2</span></h2>

<p>If you just have a few modules to convert, then all you need to do is wrap the module in this code:</p>

<pre><code>define(function(require, exports, module) {
    //Put traditional CommonJS module content here
});
</code></pre>

<p><strong>IMPORTANT</strong>: The function arguments should always be listed as <strong>require, exports, module</strong>, with those exact names and in that exact order, otherwise chaos will ensue. You can leave off exports and module from the list, but if they are needed, they need to be specified in the exact order illustrated here.</p>
</div>

<div class="section">
<h2><a name="autoconversion">Conversion Tool</a><span class="sectionMark">&sect; 3</span></h2>

<p>If you have many modules to convert, the <a href="https://github.com/jrburke/r.js">r.js project</a> has a converter tool built into the r.js file. Give it the path to the directory you want to convert and an output directory:</p>

<pre><code>node r.js -convert path/to/commonjs/modules/ path/to/output
</code></pre>

<p>There are a small number of CommonJS modules do not work well as
define()-wrapped modules. See the <a href="https://github.com/jrburke/r.js">r.js README</p> for more
information.</p>

</div>

<div class="section">
<h2><a name="exports">Setting Exported Value</a><span class="sectionMark">&sect; 4</span></h2>

<p>There are some CommonJS systems, mainly Node, that allow setting the exported value by assigning the exported value as module.exports. That idiom is supported by RequireJS, but there is another, easier way -- just return the value from the function passed to <strong>define</strong>:</p>

<pre><code>define(function (require) {
    var foo = require('foo');

    //Define this module as exporting a function
    return function () {
        foo.doSomething();
    };
});
</code></pre>

<p>With this approach, then you normally do not need the exports and module function arguments, so you can leave them off the module definition.</p>
</div>

<div class="section">
<h2><a name="altsyntax">Alternative Syntax</a><span class="sectionMark">&sect; 5</span></h2>

<p>Instead of using require() to get dependencies inside the function passed to define(), you can also specify them via a dependency array argument to define(). The order of the names in the dependency array match the order of arguments passed to the definition function passed to define(). So the above example that uses the module <strong>foo</strong>:</p>

<pre><code>define(['foo'], function (foo) {
    return function () {
        foo.doSomething();
    };
});
</code></pre>

<p>See the <a href="api.html">API docs</a> for more information on that syntax.</p>
</div>

<div class="section">
<h2><a name="packages">Loading Modules from CommonJS Packages</a><span class="sectionMark">&sect; 6</span></h2>

<p>Modules in CommonJS packages can be loaded by RequireJS by setting up the RequireJS configuration to know about the location and package attributes. See the <a href="api.html#packages">packages API section</a> for more information.</p>
</div>

<div class="section">
<h2><a name="optimize">Optimization Tool</a><span class="sectionMark">&sect; 7</span></h2>

<p>RequireJS has an optimization tool that can combine module definitions together into optimized bundles for browser delivery. It works as a command-line tool that you use as part of code deployment. See the <a href="optimization.html">optimization docs</a> for more information.</p>
</div>