How to, why to… and when not to !

React 16.6 introduced new API’s for client side code splitting. We will analyse our options of code splitting using these API’s — Route & Component based.

This article assumes that you already have some experience with creating React apps and are well versed with web-cycle of SPAs

Table of contents

1. Before you start — Benefits of CS
2. Intro to Lazy & Suspense API
3. Let’s SPLIT
4. When not to code split

1) Before you start — Benefits of CS

No matter how much we advocate SPA’s, there a fundamental problem with SPAs: excessive size of the bundle- that needs to load before browser is able to render the application. Even the smallest boilerplate applications are bound to be around 100KB. And as we start adding our logic, components, styles, behaviours, it usually shoots to MBs. Then there are additional performance lags due to client-side application’s lifecycle (web-cycle) — download javascript bundles; initialise javascript code on browser; fetch data, config & content specific to route/context; and finally render the UI (did we miss CSS?).

There are quite a few ways to solve performance lags of client-side javascript applications. One of the best possibility lies with Server-Side Rendering. However, it requires us to switch to a node server, or cache the pre-rendered HTML’s. And if you don’t intend to do SSR, your other best resolve would be code-splitting. Let’s have a look at a single bundle SPA vs. a code split SPA.

1.1 Single Bundle SPA

Here’s a sample-app-1, hosted on GitHub pages. The javascript file size is 1.2MB (non gzipped), with everything compiled inside single javascript bundle file. Below are some metrics from console, bundle analyser and Lighthouse on this app.

1.2 Code Split SPA

SPA’s with multiple output files via code splitting enables us to dynamically load only what’s required, when it is required. Code splitting emits multiple code files — chunks, which can be requested and loaded in browser, conditionally. This improves the page load time, first paint time, and even time to interactive, hence rendering our application faster and making them interactive sooner.

Let’s look at the stats, webpack bundle analyser & lighthouse audit for the same app, with code splitting, sample-app-2, hosted on GitHub pages.

Voila, the metrics have improved by .6 seconds; from 1s to .4s on an average for all the factors, by doing code splitting. We can also observe that application is visible 2 frames earlier to end user, in the lighthouse audit.

On top of performance improvements, there is a chunk ‘4’ completely dedicated to material-ui. I have intentionally included this module and imported it in the project app, and isn’t used in regular application flow. In the case without code-splitting, this code is always loaded. Whereas with code-splitting it will only be loaded if required condition is met, which is optional to completion of user’s booking journey. So if your SPA has multiple paths, like material-ui being used on a screen which is optional to booking flow, code-splitting and can help us to load the code based on user’s application usage.

If your SPA has multiple user journey paths, code-splitting and can help us to load the code based on user’s journey and application usage.

2) Intro to Lazy & Suspense API

Code splitting isn’t new, Lazy & Suspense are built on top of dynamic import, which exists from a while and is already built into webpack. However what these API really do is to standardise code splitting. This new API:

2.1 can dynamically load code pieces whenever required- at a user action/event, route level, component level, or even after page load complete.

2.2 has better controlled loading, fall-back & error handling.

2.3 doesn’t require changes to webpack scripts.

2.4 has options to load multiple code pieces, imported as separate dynamic imports, on the same event.

2.5 has an option to pull in named exports as code pieces, with minimal changes.

2.6 further, the dynamic imports internally optimises and breaks code into further modules, to have common modules as separate chunks. Out of code pieces A, B & C, any common code between A & B, or B & C, or C & A, will break out into separate chunks, and react will handle loading of these common chunks by itself on request of A, B or C.

Disclaimer

Lazy and suspense API doesn’t work for server-side code splitting yet. It solves only for dynamic loading for client side applications.

3) Let’s SPLIT

As mentioned before, we can choose to split the code as per route or components… or both. Below are examples for both these ways.

3.1 Option A — Route Based

If the SPA is built on top of react-router, easiest way to introduce React.Lazy to the router file. A basic router file looks like this:

import CompA from ‘./CompA’;
import CompB from ‘./CompB’;
import CompC from ‘./CompC’;

/* Inside React component's render method */
<Switch> 
 <Route path=’/CompA’ component={CompA}/> 
 <Route path=’/CompB’ component={CompB}/>
 <Route path=’/CompC’ component={CompC}/> 
</Switch>

Instead of the regular import from file, we will use the React.Lazy to dynamically import the module, and wrap our components with React.Suspense & an Error Boundary as below:

import React, { Suspense, lazy } from 'React';

const CompA = lazy(() => import(‘./CompA’));
const CompB = lazy(() => import(‘./CompB’));
const CompC = lazy(() => import(‘./CompC’));

/* Inside React component's render method */

/* ErrorBoundary is to render fallback ui incase of errors */  <ErrorBoundary>
 <Suspense fallback={<div>Loading…</div>}>
    <Switch> 
     <Route exact path=’/’ component={LoaderHOC(CompA)}/> 
     <Route path=’/CompB’ component={LoaderHOC(CompB)}/>
     <Route path=’/CompC’ component={LoaderHOC(CompC)}/> 
    </Switch>
  </Suspense>
</ErrorBoundary>

The code uses Lazy, Suspense & Error Boundaries as detailed below:

1. React.Lazy — accepts a function that must call dynamic import. This must return a Promise that resolves to a module with a default export containing a React component. This will automatically load the bundle containing the ‘CompA’ when the route matches to ‘/CompA’, and so on. The dynamic code syntax instructs webpack to split in separate chunks & tree shaking optimises chunks — depending on the code-structure and components shared between dynamically imported modules, it may even split it into multiple files per route. Loading these additional chunks per route is all taken care by React and Webpack.
2. React.Suspense — will display a fall-back component, while loading the requested module in browser. We can also extend the ‘fall-back’ to be an animated pre-loader… or as I did, use the header navigation component and a skeletal. The fall-back component becomes part of the main chunk, or even a separate chunk based on your code structure.
3. ErrorBoundary — is another HOC that is used to capture any run-time code errors inside the child modules, or even network errors if the module is not loaded. A sample error boundary wrapper to check for network errors would look like:

That’s it. We can run a bundle-analyser or inspect in the browser’s network panel and see this in action. I would recommend to run a bundle-analyser on your code, and see if there is any further optimisation you can figure out. For best results, remove any unused imports from each and every file in your code base.

Check out a sample demo with code of Route Level Code splitting with Lazy/Suspense on the same sample app we analysed before in step 1 — sample-app-3.

3.2 Option B — Component Based

As per Code Splitting, loading the next required code piece is dependent on a Decision-Making ‘event’. As seen above, with Route based code splitting, this decision event is tagged to the Application Route, and implemented using React’s Router. With Component based chunks, we can have flexibility to tag this event to various types of actions — scrolling of the page or any other user interaction action, any internal app lifecycle action like config or data, or even based on user’s activity on the app.

Let’s consider use-case of a multi-step booking SPA. The next view of the application depends on whether user selects one way journey or return journey. As such, we can check user’s selection and dynamically load next component. This also helps us to avoid loading pieces of code, that are not required for a particular user, as per the choices he makes in the application flow.

To do this, we would need to write a function (getViewComponent), that accepts the component identifier and returns the react component. This method is almost similar to ‘LoaderHOC’ written above for route level splitting, except that it accepts a string name instead of the component itself, to enable dynamic request for components by string names.

import React, { Suspense, lazy } from 'React';

const AOneWay = lazy(() => import(‘./CompAOneWay’));
const AReturn = lazy(() => import(‘./CompAReturn’));
const BOneWay = lazy(() => import(‘./CompBOneWay’));
const BReturn = lazy(() => import(‘./CompBReturn’));
const MapChunk = {AOneWay, AReturn, BOneWay, BReturn};

const getViewComponent = (view) => {
 const Element = MapChunk[view];
 return 
  <ErrorBoundary>
   <Suspense fallback={<div>Loading…</div>}>
     <Element />
   </Suspense>
  <ErrorBoundary>
};

class Main extends React.Component {
 changeView(name) {
  if(this.state.isReturnJourney) {
    this.setState({currentView, name + ‘OneWay’});
  }
  else {
    this.setState({currentView, name + ‘Return’});
  }
 }

 onNextClick(e) {
  this.changeView(‘CompB’);
 }

 render() {
  <div> {getViewComponent(this.state.currentView)} </div>
 }
}

The code uses Lazy, Suspense & Error Boundaries in a same way we used them for route level chunks. It additionally uses MapChunk, getViewComponent & the Main Class’s internal state, as below:

1. MapChunk — is a simple javascript object, that keeps a map of all react component references. Using the React Component variables in this way, doesn’t load them into browser, and still maintains out Lazy+Suspense lifecycle.
2. getViewComponent — is simply an engine that picks up string name, and converts it into React Component. It refers to MapChunk, and uses Lazy+Suspense to load the required module file to browser, if it isn’t loaded already.
3. Main State Variable — we use this state variable to keep maintain the view. This needs to be maintained in your topmost container inside Provider. The currentView variable holds the current set state of the application derived from user’s action. It is updated to next view, whenever user performs the next event.

And that’s it. Check out a sample demo with code of Component Level Code splitting with Lazy/Suspense. You can run the bundle analyser provided in the sample codebase and see the results. To compare, simply change React.Lazy imports to regular imports, and you’ll see output as a single file.

4. When not to split!

After such a long article promoting code splitting and looking at its benefits, you may wonder if there could be any drawback at all? But there is always a catch. There are some scenarios worth considering before moving into the world of Client Side Code-Splitting:

4.1 Delayed initialisation

Let’s look at the network panel of code-split application, we observed earlier.

The problem here is, the primary chunk, that is injected to the html page, will download, initialise and then request additional chunks. This delays the Document Load event, because substantial amount of javascript has to be executed, before it can request additional modules. So it’s better to ensure you keep your primary or main entry route to SPA, or main components, in the main chunk. Or play around with dynamic imports as per applications web-cycle and analyse results.

There are couple of more ways to fix it, by identifying the route at server and injecting all the files required for first print for each route on the page itself to avoid this behaviour. But then we step into realms of SSR, and it’s not out-of-the-box implemented by this API. So, if your code split bundle output requires you to have chain of javascript files to load… its maybe better to not do code splitting. Run some tests and figure out what works better for your use case.

4.2 Caching problems

Another set of issue is with caching of code split chunks — To improve performance, a best practice is to add caching to all resources, including HTML page & all JS files. With chunks, we usually put a hash on file names: to serve latest files on re-deployments. With html file being cached, browser will always look for the same hash javascript files.

The simplest way to avoid caching issues is to remove caching from html file, and use caching only on javascript files with hash keys. So it will always load the new HTML file with updated hash-keys. And even if there is no new deployments before a user re-access the application, the javascript files will be picked from browser’s cache, as hash key remains same in HTML.

There are other nuances with caching with Code Splitting, so ensure you validate performance and see if code splitting is really effective with your caching strategy.

In the end, thank you for reading, shout out questions in comments if you have any.

References