How to use RequireJS with jQuery

Global Functions § 2

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 noConflict function that supports releasing control of the global variables and this can be automated in your requirejs.config, as we will see later.

Module Name § 3

jQuery defines named AMD module 'jquery' (all lower case) when it detects AMD/RequireJS. To reduce confusion, we recommend using 'jquery' as the module name in your requirejs.config.

Example:

requirejs.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'
    }
});

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.

You can avoid lots of configuration lines by placing the files according to the default ID-to-path convention of baseUrl + moduleID + '.js'. 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.

So to reiterate, you will likely get an error if you refer to jQuery with another module name, like 'lib/jquery'. This example will not work:

    // THIS WILL NOT WORK
    define(['lib/jquery'], function ($) {...});

It will not work, since jQuery registers itself with the name of 'jquery' and not 'lib/jquery'. In general, explicitly naming modules in the define() call are discouraged, but jQuery has some special constraints.

Example using shim config § 4

This example shows how to use the shim config to specify dependencies for jQuery plugins that do not call define(). 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().

Example using jQuery with shim config

Example loading jquery from a CDN § 5

This example shows how to load and optimize your code while loading jQuery from a Content Delivery Network (CDN). This example requires all your jQuery plugins to call define() to properly express their dependencies. Shim config does not work after optimization builds with CDN resources.

Example using jQuery from a CDN

Mapping Modules to use noConflict § 6

If all of your modules (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 requirejs(['jquery']), you can use the map config to map the use of jQuery to a module that calls noConflict and returns that value of jQuery for the 'jquery' module ID.

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

requirejs.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 );
});

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

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

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

requirejs(['jquery'], function( ) {
    console.log( $ ) // UNDEFINED!
});

The previous example with a concatenated require-jquery file § 7

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, you can find require-jquery here.