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

<div id="directory" class="section">
<h1>How to use RequireJS with jQuery</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="#globalvars">Global Functions</a><span class="spacer boxFlex"></span><span class="sect">&sect; 2</span>
    </li>
    <li class="hbox">
        <a href="#modulename">Module Name</a><span class="spacer boxFlex"></span><span class="sect">&sect; 3</span>
    </li>
    <li class="hbox">
        <a href="#shimconfig">Example using shim config</a><span class="spacer boxFlex"></span><span class="sect">&sect; 4</span>
    </li>
    <li class="hbox">
        <a href="#cdnconfig">Example loading jquery from a CDN</a><span class="spacer boxflex"></span><span class="sect">&sect; 5</span>
    </li>
    <li class="hbox">
        <a href="#noconflictmap">Mapping Modules to use noConflict</a><span class="spacer boxflex"></span><span class="sect">&sect; 6</span>
    </li>
    <li class="hbox">
        <a href="#oldexample">The previous example with a concatenated require-jquery file</a><span class="spacer boxflex"></span><span class="sect">&sect; 7</span>
    </li>
</ul>
</div>

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

<p>While RequireJS loads jQuery just like any other dependency, jQuery's wide use and extensive plugin ecosystem mean you'll likely have other scripts in your project that also depend on jQuery. You might approach your jQuery RequireJS configuration differently depending on whether you are starting a new project or whether you are adapting existing code.</p>

<div class="section">
<h2>
<a name="globalvars" href="#globalvars">Global Functions</a>
<span class="sectionMark">&sect; 2</span>
</h2>
<p>jQuery registers itself as the global variables "$" and "jQuery", even when it detects AMD/RequireJS. The AMD approach advises against the use of global functions, but the decision to turn off these jQuery globals hinges on whether you have non-AMD code that depends on them. jQuery has a <a href="http://api.jquery.com/jQuery.noConflict/">noConflict function</a> that supports releasing control of the global variables and this can be automated in your require.config, as we will see <a href="#noconflictmap">later</a>.</p>
</div>

<div class="section">
<h2>
<a name="modulename" href="#modulename">Module Name</a>
<span class="sectionMark">&sect; 3</span>
</h2>

<p>jQuery defines <a href="api.html#modulename">named AMD module</a> 'jquery' (all lower case) when it detects AMD/RequireJS. To reduce confusion, we recommend using 'jquery' as the module name in your require.config.

<p>Example:</p>

<pre><code>require.config({
    baseUrl: 'js/lib',
    paths: {
        // the left side is the module ID,
        // the right side is the path to
        // the jQuery file, relative to baseUrl.
        // Also, the path should NOT include
        // the '.js' file extension. This example
        // is using jQuery 1.9.0 located at
        // js/lib/jquery-1.9.0.js, relative to
        // the HTML page.
        jquery: 'jquery-1.9.0'
    }
});
</code></pre>

<p>The other (recommended) solution is to just name the file 'jquery.js' and
    place it in the baseUrl directory. Then the above paths entry is not needed.</p>

<p>You can avoid lots of configuration lines by placing the files according to
    the default ID-to-path convention of
    <code>baseUrl + moduleID + '.js'</code>. The examples below show how to
    set baseUrl to be the directory for third-party, library code, and use
    one extra paths config for your app code.</p>
</div>

<div class="section">
<h2>
<a name="shimconfig" href="#shimconfig">Example using shim config</a>
<span class="sectionMark">&sect; 4</span>
</h2>

<p>This example shows how to use the <a href="api.html#config-shim">shim config</a> to specify dependencies for jQuery plugins that do not call <a href="api.html#define">define()</a>. This example is useful if you have an existing jQuery project you want to convert and do not want to modify the sources of the jQuery plugins to call define().</p>

<h4><a class="download" href="http://github.com/requirejs/example-jquery-shim">Example using jQuery with shim config</a></h4>

</div>

<div class="section">
<h2>
<a name="cdnconfig" href="#cdnconfig">Example loading jquery from a CDN</a>
<span class="sectionMark">&sect; 5</span>
</h2>

<p>This is an example on how to load an optimize your code while loading jQuery from a <a href="http://en.wikipedia.org/wiki/Content_delivery_network">Content Delivery Network</a> (CDN). This example requires all your jQuery plugins to call <a href="api.html#define">define()</a> to properly express their dependencies. <a href="api.html#config-shim">Shim config</a> does not work after optimization builds with CDN resources.</p>

<h4><a class="download" href="http://github.com/requirejs/example-jquery-cdn">Example using jQuery from a CDN</a></h4>

</div>

<div class="section">
<h2>
<a name="noconflictmap" href="#cdnconfig">Mapping Modules to use noConflict</a>
<span class="sectionMark">&sect; 6</span>
</h2>

<p>If <strong>all of your modules</strong> (including any third party jQuery plugins or library code that depend on jQuery) are AMD compatible and you want to avoid having $ or jQuery in the global namespace when they call <code>require(['jquery'])</code>, you can use the <a href="api.html#config-map">map config</a> to map the use of jQuery to a module that calls noConflict and returns that value of jQuery for the 'jquery' module ID.</p>

<p>You can use this example with the CDN example above -- the shim example will not work since shimmed libraries need a global jQuery.</p>

<pre><code>require.config({
    // Add this map config in addition to any baseUrl or
    // paths config you may already have in the project.
    map: {
      // '*' means all modules will get 'jquery-private'
      // for their 'jquery' dependency.
      '*': { 'jquery': 'jquery-private' },

      // 'jquery-private' wants the real jQuery module
      // though. If this line was not here, there would
      // be an unresolvable cyclic dependency.
      'jquery-private': { 'jquery': 'jquery' }
    }
});

// and the 'jquery-private' module, in the
// jquery-private.js file:
define(['jquery'], function (jq) {
    return jq.noConflict( true );
});
</code></pre>


<p>This means that any module which uses jQuery will need to use the AMD return value rather than depending on the global $:</p>

<pre><code>
require(['jquery'], function( $ ) {
    console.log( $ ) // OK
});

require(['jquery'], function( jq ) {
    console.log( jq ) // OK
});

require(['jquery'], function( ) {
    console.log( $ ) // UNDEFINED!
});
</code></pre>

</div>

<div class="section">
<h2>
<a name="oldexample">The previous example with a concatenated require-jquery file</a>
<span class="sectionMark">&sect; 7</span>
</h2>
<p>
Previously, we've been pointing to an example using a special require-jquery file, which consisted of require.js and jQuery concatenated. This is no longer the recommended way to use jQuery with require.js, but if you're looking for the (no longer maintained) example, <a href="https://github.com/jrburke/require-jquery">you can find require-jquery here</a>.
</p>
</div>