Configure JavaScript resources

Overview

JavaScript is important for making your storefront dynamic and interactive. However, including JavaScript into the page headers might slow down uploading of the pages. To address this problem, we exclude JavaScript from the page headers and we added the ability to use the RequireJS library.

RequireJS improves the perceived page load time because it allows JavaScript to load in the background; in particular, because it enables asynchronous or 鈥渓azy鈥� JavaScript loading.

Explore and configure JavaScript resources

You must specify and configure all JavaScript resources used in modules and themes that you added or customized. To ensure correct work of themes and modules, do not edit the JavaScript resources belonging to other modules and themes.

JavaScript resources can be specified as follows:

• Library level for all libraries in Magento code base (lib/web)
• Module level for all libraries in a module (<module_dir>/view/<areaname>/web)
• Theme for all libraries in a theme (<theme_dir>/<VendorName>_<ModuleName>/web)
• (Not recommended) All libraries in a theme (<theme_dir>/web). We do not recommend using this level to specify JavaScript resources.

We recommend specifying JavaScript resources in the templates rather than in the layout updates to ensure processing of the resources in body of a page.

JavaScript resources generated in Magento have IDs of two types: a RequireJS ID and a Magento modular ID. For example JavaScript resources for configurable product will have the following IDs:

// Regular ID
require(["jquery"], function($){
    // ...
});

// Modular ID (Magento module: Magento_ConfigurableProduct, resource: js/configurable)
require(["magento!Magento_ConfigurableProduct::js/configurable"], function(Configurable){
    // ...
});

The modular ID has magento! prefix and is used for loading the JavaScript modules. The ID Normalizer plugin converts the modular IDs into the file paths that are used by RequireJS to load the JavaScript modules.

Specify dependencies between JavaScript resources

Specifying all dependencies between JavaScript resources might be time consuming. To facilitate this task we implemented ability to build the dependencies via plugin: thus, you will need to specify only dependency of your resource on a plugin, and the latter will pick up all necessary dependencies on other resources automatically.

When creating a new resource, you can select a plugin, on which your resources are to depend, from the ready-to-go plugin library or write a plugin by yourself. Observe the following rules when declaring a plugin:

1. To declare a plugin, use the define function:

define(["jquery"], function($){
  // plugin code
  // where $ == "jquery"
})(jQuery); 

2. If you need a plugin to be used in various environments, specify it as follows:

(function (factory) {
    if (typeof define === 'function' && define.amd) {
        // AMD. Register as an anonymous module.
        define(['jquery'], factory);
    } else {
        // Browser globals
        factory(jQuery);
    }
}(function ($) {
  // plugin code
  // where $ == jQuery
}));

3. To build a dependency on the third-party plugin, specify a shim in the following configuration files:
• requirejs-config.js

var config = {
  "shim": {
    "3-rd-party-plugin": ["jquery"]
  }
};

• {third-party-plugin}.js

!(function($){
  // plugin code
  // where $ == jQuery
})(jQuery);

Configure the RequireJS library

The RequireJS library loads JavaScript files and modules. To make this library available in your Magento instance, specify this library along with specific RequireJS configurations in layout.xml as follows:

Specify JavaScript resources mapping

To work with the RequireJS library, specify the mapping of JavaScript resources; that is, assign the aliases to resources. Use requires-config.js to create the mapping.

To make your configurations more precise and specific for different modules/themes, you can identify mapping in requires-config.js file at several levels depending on your needs. All configurations will be collected and executed in the following order:

1. Library configurations.
2. Configurations at the module level.

Dependencies between the modules or themes are considered as well.

3. Configurations at the theme module level for the ancestor themes.
4. Configurations at the theme module level for a current theme.
5. Configurations at the theme level for the ancestor themes.
6. Configurations at the theme level for the current theme.

In addition to standard aliases of RequireJS library, Magento uses module notations or relative paths. You must specify in RequireJS configurations the relative paths to JavaScript resources belonging to the module and the theme module levels. For instance, specifying the path in app/code/Magento/Catalog/view/frontend/requirejs-config.js will look as follows:

var config = {
    paths: {
        // configuration for resource 'app/code/Magento/Catalog/view/frontend/product/product.js'
        "product": "./product/product"
    }
};

In the example above, ./product/product is relative path to JavaScript resources of Catalog module.

You should not specify baseUrl parameter in the configurations files, since it is generated automatically.

Adjust RequireJS

You can adjust RequireJS for your needs in two ways:

• Fallback mechanism: general rules on customizing URLs or paths for static view files apply to JavaScript, because JavaScript files are static view files
• Configuration files as described earlier in Configure the RequireJS library