Code Splitting

Code splitting refers to breaking up a JavaScript bundle into smaller bundles that can be progressively loaded as needed in the client. This is done by dynamically importing a module. In steal this is done with steal.import:

steal.import("app/pages/login").then(function(login){
  document.body.appendChild(login());
});

API

The following are important APIs to configure code splitting.

• steal.import: A function to dynamically import a module. In production this will load a split bundle that contains this module.
• bundle configuration: Specifies the split points. This usually coincides with each module that you dynamically import with steal.import.
• maxBundleRequests: A steal-tools build option, this specifies the number of bundles that should be for any particular bundle.
• maxMainRequests: Usually used in Multi-main Builds, this is like maxBundleRequests but is applied to the main.

Adding code splitting

If you have an existing application that doesn't do any dynamic module loading, adding code splitting is a great performance enhancement.

Progressively loading modules

As an example, consider this module when imports login and home pages statically:

import login from "~/pages/login";
import home from "~/pages/home";

let page = location.pathname.substr(1);
if(page === "login") {
  document.body.appendChild(login());
} else if(page === "home") {
  document.body.appendChild(home());
}

We can prevent loading these two modules before they are needed by using steal.import to dynamically load them:

function render(pageComponent) {
  document.body.appendChild(login());
}

let page = location.pathname.substr(1);

steal.import(`~/pages/${page}`).then(function(pageComponent){
  render(pageComponent);
});

This is what refactoring an application to include progressive loading usually consists of; moving some functionality into a function (in this case the render function), and calling that function after using steal.import.

Setting split points

Now the application code is fixed, but to get separate bundles add the bundle configuration to your package.json:

{
  "steal": {
    "bundle": [
      "app/pages/login",
      "app/pages/home"
    ]
  }
}

The bundle names used here should be module names like app/pages/login, and include the package name. Do not use the ~ alias, steal-tools won't now how to find these modules.

Specifying bundle depth

In a large application it is possible that steal-tools will create a large number of bundles because there is a lot of sharing between bundles. By default steal-tools will let there be no more than 3 bundles loaded for a particular split-point.

This is controlled with the maxBundleRequests configuration. You might want to adjust this number to be higher/lower depending on your application. It can be changed in your build script like so:

var stealTools = require("steal-tools");

stealTools.build({}, {
  maxBundleRequests: 5
});

Bundling algorithm

What makes steal-tools code-splitting special is its two-pass algorithm that effectively weighs number of bundles and bundle-size. See the video below to learn how the algorithm works: