webpack require.ensure first parameter use

Question

What is the use of first parameter of webpack require.ensure first parameter?

https://webpack.github.io/docs/code-splitting.html

require.ensure(dependencies, callback)

I tried to let the first parameter filled or empty like:

require.ensure(['./module'], function() {  //filled first param

require.ensure([], function() {  //empty first param
  let module = require('./module');
  $ocLazyLoad.load([{
    name: module.default,
  }]);
});

Both are working. So what is the use of the first parameter?

There is also a require.include function in the documentation which I do not understand the use case of this function. Can anyone explain it too?

Homogenous

Answer 1

These functions have to do with Code Splitting, which allows some sections of code to be bundled separate from the main code, and loaded and run later, while the code is running.

Code Sample 1:

require.ensure(['./module'], function() {  //filled first param

The first parameter is an array of modules to ensure are loaded before running the callback. If ./module has not been loaded in one of the bundles yet, it will load the chunk this module is contained in a new HTTP request, then call the callback function.

To use Webpack's example:

require.ensure(["module-a", "module-b"], function(require) {
    var a = require("module-a");
    // ...
});

module-a and module-b can now be split into different files, and the callback function will not run until they have loaded.

Code Sample 2:

require.ensure([], function() {  //empty first param
  let module = require('./module');
  $ocLazyLoad.load([{
    name: module.default,
  }]);
});

Here require.ensure defines a split point. As it does not have any dependencies in the array, it does not itself load any modules. However, require statements inside the callback will still be dynamically loaded through the magic of webpack and ./module will be bundled in a separate file.

require.include

There is also a require.include function in the documentation which I do not understand the use case of this function. Can anyone explain it too?

require.include can be used to ensure a module is bundled, even if it is not require-ed. Normally if a module is not require-ed, it will not be bundled at all. This can be used to force it to include the module, even it not requir-ed in the bundle itself.

Pressing

Great question / answer, this area of webpack gets confusing quickly. What is the point of Code Sample 2 if the require.ensure does nothing, would we get the same result by dropping it and requiring the module at the top of the file? I see this pattern used with react-router for async routes here. Why do the react-router examples not list the module dependencies that they are about to load asynchronously? – Subconscious

@Subconscious yeah, why do react-router example does not list the module dependencies at ensure when they want to load asynchronously, is it a mistake on react-router examples or the answer for Code Sample 2 is incorrect? – Homogenous

for require.include, what's the point of having require.include when I can just require it normally? – Homogenous

code sample 2's description isn't correct and that is really the core of the above question. It still creates a split for any modules required inside of the ensure. – Domett

@Domett Thanks for the correction, it seems I must made a mistake in my testing. – Phanerogam

What is the purpose of the first way of loading if the second one is absolutely the same? – Druce

Still not clear. what's the purpose of require.include? the doc says, require.include just put the file into bundle , but not to execute it. Which case should I use it ? – Denouement

Answer 2

The first parameter is rarely useful. To learn why it is there and causes confusion, please see my another answer.

Comply with the spec

One use case for the first parameter could be to specify all dependencies for clarity and to comply with the spec. But that's completely optional.

Add modules to chunks to make the chunks similar

Consider you have two split points in different parts of an app. The first split point depends on module a, the second depends on modules a and b. To eliminate the risk of downloading a twice, you could decide to place both modules into a single chunk:

// First split point
require.ensure(['b'], (require) => {
  require('a');
});

Pull modules into parent chunks

Consider the following code splitting scenario:

require.ensure([], (require) => {
  ...
  require.ensure([], (require) => {
    require('a');
    require('b');
  });

  require.ensure([], (require) => {
    require('a');
    require('c');
  });
  ...
});

In this case, module a will end up in both nested chunks. If at least one of the nested chunks is frequently loaded, you could decide to move a into the parent chunk:

require.ensure(['a'], (require) => {
  ...

Add modules to chunks with require.include

Consider the previous example. There is another way to pull a into the parent chunk:

require.ensure([], (require) => {
  require.include('a');
  ...

In this particular example, both solutions are equivalent and there is no advantage in using require.include. However, if you don't have access to the split point's code, parent chunk is an entry chunk or you use the modern import() syntax, require.include is your only choice.

It is possible to pull modules into chunks using synchronous require or import. The advantage of require.include is that it only loads modules and doesn't evaluate them. This could be useful to defer modules' evaluation if it is expensive or depends on the application state, e.g., requires polyfills to be loaded, DOM nodes to be present, etc.

Depressed