How to do code splitting

From PageBuilder Engine 3.0 release and later, you now have 2 different ways to do code splitting.

• Using dynamic imports for Webpack code splitting. This allows you to split both the CSS and the JS for the code into a separate chunk that can be loaded later. In previous releases, we only supported splitting the JS, but the 3.0 release also allows you to split the CSS. For more information, see Code splitting and dynamic import.

• Using the new lazy attribute for Engine code splitting. For more information, continue reading.

Code splitting with server-side rendering

The new built-in code splitting was designed with both server-side rendering and mono-bundle in mind. Components that are code split will still render regularly on the server-side render. The only change is there will be an additional wrapping div with a data-fusion-lazy-id attribute set. This allows Engine to show the server-side rendered HTML while the JS chunk is being loaded.

Because the element is immediately visible on the page, the CSS for the component will be included in main CSS bundle. This is true even if your component fails to render server-side (or if you specifically check for it by using typeof window === 'undefined). If you want the CSS to be split into a separate chunk, you will need to handle code splitting yourself through dynamic imports.

Note

You should not render anything that could mutate the DOM in your server-side render. This includes iframes and scripts. Doing so could cause the elements to be loaded more than once.

When to use code splitting

Being able to code split and still render on the server-side is a very powerful tool. This allows you to code split features that are needed for crawlers and SEO. However, code splitting a component has the following disadvantages:

• Additional network request(s) to load the chunk(s).

• The component is slower to become interactive, compared to other components.

• The overall size is marginally larger because of the extra logic to load the chunk.

There is no hard rule on when something should be code split, but we recommend only doing it for components importing large packages that readers do not need to immediately interact with.

Note

When using code splitting with SPA enabled, the chunk(s) for the component will not be loaded until it is used on the page. If it is used again on a subsequent page, the loaded chunk(s) will be reused and the component will become interactive at the same time as the non-lazy components on the page.

Using Engine-provided code splitting

In order to mark a component for code splitting, simply add a lazy=true property to it. Here’s an example:

import React from 'react';
import DatePicker from 'react-datetime';
import 'react-datetime/css/react-datetime.css';

const Feature = () => <DatePicker />;
Feature.lazy = true; // code split this for all output types

export default Feature;

You can also enable code splitting just for certain output types by using lazy=[output1, output2]. Here’s an example:

import React from 'react';
import DatePicker from 'react-datetime';
import 'react-datetime/css/react-datetime.css';

const Feature = () => <DatePicker />;
Feature.lazy = ['default']; // only code split this for the default output type

export default Feature;

The lazy property can be added to features, chains, and layouts. If applied to a chain or a layout, all children will only be able to render once the JS for the chain/layout has been loaded. This means that if you have any non-lazy components in a lazy chain/layout, the component will not become interactive until the chain/layout is finished loading and re-rendering. Engine also will be unable to strip out the JS from the mono-bundle for those non-lazy components, as they could be used elsewhere.

If both static and lazy are set on a component, Engine will treat it as static. The only time this might be applicable is if you have one set of output types where the component should be static and another where it should be lazy.

Error behavior

If a code split component fails to render client-side (either because the chunk failed to load or because an error was thrown), the component will continue to show the server-side rendered HTML. If there is no server-side rendered HTML, you will see an empty div rendered for the component. When testing code split components, make sure to check your developer console and try to use the component to verify it rendered successfully.