Thanks to Adarsh Manickam for contributing this topic!

RequireJS in Commerce

This topic describes general concepts of how the RequireJS library is used in the application with examples. Please refer to official RequireJS documentation for in-depth explanation.

RequireJS is a JavaScript file and module loader. It improves perceived page load times because it allows JavaScript to load in the background. In particular, it enables asynchronous JavaScript loading.

Configuration

All configuration is done in the requirejs-config.js file. It has a single root object config which contains the configuration options described below. All the configuration settings are optional and are used only when required. The following snippet is a sample requirejs-config.js describing the structure of the file. Example requirejs-config.js file

var config = {
    map: {...},
    paths: {...},
    deps: [...],
    shim: {...},
    config: {
        mixins: {...},
        text: {...}
    }
}
Copied to your clipboard
var config = {
    map: {...},
    paths: {...},
    deps: [...],
    shim: {...},
    config: {
        mixins: {...},
        text: {...}
    }
}

map

The map configuration maps (connects) any real AMD modules that calls define(), to the specified alias. In the snippet below, * means all loaded RequireJS modules can use the specified alias. The second mapping applies only in the context of Vendor_Module/js/amd-module. So, both types of contexts can be applied: either a global context, or a module specific context.

map: {
    '*': {
        alias: 'Vendor_Module/js/complex/path/amd-module'
    },
    'Vendor_Module/js/amd-module': {
        alias-two: 'Vendor_Module/js/complex/path/amd-module-two'
    }
}
Copied to your clipboard
map: {
    '*': {
        alias: 'Vendor_Module/js/complex/path/amd-module'
    },
    'Vendor_Module/js/amd-module': {
        alias-two: 'Vendor_Module/js/complex/path/amd-module-two'
    }
}

Now we can use our Vendor_Module/js/complex/path/module using alias in any RequireJS module or config file without needing to type the entire path. For example, catalogAddToCart is mapped to Magento_Catalog/js/catalog-add-to-cart and can be used anywhere as a RequireJS module name. In the next example, catalogAddToCart is mapped to Magento_Catalog/js/catalog-add-to-cart only in the context of the discountCode module.

map: {
    '*': {
        catalogAddToCart: 'Magento_Catalog/js/catalog-add-to-cart'
    },
    'discountCode': {
        catalogAddToCart: 'Magento_Catalog/js/catalog-add-to-cart'
    }
}
Copied to your clipboard
map: {
    '*': {
        catalogAddToCart: 'Magento_Catalog/js/catalog-add-to-cart'
    },
    'discountCode': {
        catalogAddToCart: 'Magento_Catalog/js/catalog-add-to-cart'
    }
}

You can also use the map configuration to override a JS module with a custom JS module. See Custom JS component.

paths

The paths configuration, similar to map, is used for aliasing not just any real AMD module that calls define(), but also any JS file (even from a URL), HTML templates, etc. The application uses this to alias URLs and third-party libraries.

paths: {
    'alias': 'library/file',
    'another-alias': 'https://some-library.com/file'
}
Copied to your clipboard
paths: {
    'alias': 'library/file',
    'another-alias': 'https://some-library.com/file'
}

When setting a path to an array with multiple script sources, if the first script fails to load, the next is used as a fallback.

var config = {
    ...
    paths: {
        'alias': [
            'https://some-library.com/file',
            'vendor_name>_<module_name>/js/file'
        ]
    }
};
Copied to your clipboard
var config = {
    ...
    paths: {
        'alias': [
            'https://some-library.com/file',
            'vendor_name>_<module_name>/js/file'
        ]
    }
};

For external content, resources should be whitelisted; otherwise the application raises error notices in the browser console. See Content Security Policies.

Consider the example of overwriting an HTML file in the adminhtml. In this example, the max-length value of the text-box in the adminhtml is altered. The HTML file is located at vendor/magento/module_ui/view/base/web/templates/form/element/input.html.

Create a requirejs-config.js file under app/code/<Vendor_Name>/<Module_Name>/view/base/ and add the following code:

var config = {
    paths: {
        'ui/template/form/element/input': '<vendor_name>_<module_name>/template/form/element/input'
    }
};
Copied to your clipboard
var config = {
    paths: {
        'ui/template/form/element/input': '<vendor_name>_<module_name>/template/form/element/input'
    }
};

Create an input.html file under app/code/<Vendor_Name>/<Module_Name>/view/base/web/template/form/element/ and copy the contents of the input.html file from the module_ui template file.
Change the maxlength value to 512, which was originally set to 256.

Upgrade the application:

bin/magento setup:upgrade
Copied to your clipboard
bin/magento setup:upgrade

Generate the dependency injection configuration:

bin/magento setup:di:compile
Copied to your clipboard
bin/magento setup:di:compile

Confirm the modification by inspecting the element source code and check the maxlength value, which should be 512 as specified in the template.

The path for Magento_Ui/templates is set to be ui/template in the requirejs-config.js module of module_ui, hence ui/template is used for specifying the path. If no paths are set, <module_name>/templates should be used.

deps

The deps configuration is used to add a dependency. It can either be used directly under var config = {} or under a shim configuration. Adding modules under an independent deps configuration will load the specified modules in all pages.

In this snippet, the custom Vendor_Module/js/module will be loaded in all pages.

deps: ['Vendor_Module/js/module']
Copied to your clipboard
deps: ['Vendor_Module/js/module']

shim

The shim configuration is used to build a dependency on a third party library, since we cannot modify it.

When to use the shim configuration:

To add a new dependency to a third party library
To add a new dependency to a third party library which does not use an AMD module
To change load order by adding a dependency to a third party library

In this snippet, dependencies are added directly in an array, or it can be specified as an array under the deps key. The exports key is used to specify under what identifier the module is exported into. This export identifier can be used to access it.

shim: {
    '3rd-party-library': ['myJSFile'],
    'another-3rd-party-library': {
        deps: ['myJSFile'],
        exports: 'another3rdPartyLibrary'
    }
}
Copied to your clipboard
shim: {
    '3rd-party-library': ['myJSFile'],
    'another-3rd-party-library': {
        deps: ['myJSFile'],
        exports: 'another3rdPartyLibrary'
    }
}

mixins

The mixins configuration is used to overwrite component methods of an AMD module which returns either a UI component, a jQuery widget, or a JS object. Unlike the above configuration properties, the mixins property is under the config property, apart from the parent object called config.

In this snippet, Vendor_Module/js/module-mixin will overwrite the existing component methods in Vendor_Module/js/module with the specified component methods. It is a convention to name the mixin by appending a -mixin to the original path/to/js, although not required.

config: {
    mixins: {
        'Vendor_Module/js/module': {
            'Vendor_Module/js/module-mixin': true
        }
    }
}
Copied to your clipboard
config: {
    mixins: {
        'Vendor_Module/js/module': {
            'Vendor_Module/js/module-mixin': true
        }
    }
}

The concept of Javascript mixins itself is explained in depth in Using Javascript Mixins.

text

The text configuration is used to set the security request headers using the text.js file.

Without Cross Origin Resource Sharing (CORS) it is not possible to add the X-Requested-With header to a cross domain XHR request. Set this header to tell the server that the request was initiated from the same domain.

config: {
    text: {
        'headers': {
            'X-Requested-With': 'XMLHttpRequest'
        }
    }
}
Copied to your clipboard
config: {
    text: {
        'headers': {
            'X-Requested-With': 'XMLHttpRequest'
        }
    }
}