Guide 01 · Developer docs

Choosing how to build

Decide where the pages of a Core dna site are composed before writing code: on the platform, in your own application, or on the platform with a few pieces filled in by the browser. The decision tree, each shape in depth, multi-brand and languages, and a table and case studies to make the call.

L2
Unit 04 · Hybrid, the common case

Splitting bundles

Hybrid, the common case Page 20 of 29 Updated

An island on a landing page should not pull the checkout's JavaScript in with it. One webpack entry per part of the site, each loaded only by the templates that need it, and a size budget that fails the build when an entry grows.

Who this is for. The JavaScript developer setting up a hybrid site's build. After this page each part of the site downloads only its own code, and a regression in size is caught by the build rather than by a visitor on a phone.

One entry per part of the site

Give each distinct part of the site its own webpack entry: the code every page needs, the checkout, the account area, a personalisation bundle that is loaded only when it is switched on. Libraries that only one action needs, such as a payment provider's SDK or a PDF library, are loaded with import() when that action happens, and become chunks of their own. The budget below is from a production theme that sells courses:

JavaScript webpack.config.js 
const isProd = process.env.NODE_ENV === 'production';

module.exports = {
  entry: {
    main: './src/js/main.js',
    cart: './src/js/cart.js',
    checkout: './src/js/checkout.js',
    account: './src/js/account.js',
  },
  output: {
    filename: 'js/[name].bundle.js',
    chunkFilename: 'js/[name].bundle.js',
  },
  performance: {
    // A budget that breaks the production build instead of printing a warning
    hints: isProd ? 'error' : 'warning',
    maxEntrypointSize: 150 * 1024,
    maxAssetSize: 100 * 1024,
    // Large libraries loaded on demand with import() are left out of the budget
    assetFilter: (file) => !/(stripe-pay|receipt-pdf)\.bundle\.js$/.test(file),
  },
};

Loading an entry only where it is used

The base template loads what every page needs and leaves a block for the rest; a template that needs more adds to it. Every script tag carries the nonce, and the ?v= from the deploy's commit hash makes browsers fetch the new file after each deploy:

Template code templates/checkouts/single-page.html 
{extends file='includes/base-template.html'}

{block name='scripts' append}
  <script src="/dist/js/checkout.bundle.js?v={$_currentSite->getLastVcsHash()}" nonce="{$_inlineScriptNonce}" defer></script>
{/block}
{% extends 'includes/base-template.html' %}

{% block scripts %}
  {{ parent() }}
  <script src="/dist/js/checkout.bundle.js?v={{ _currentSite.getLastVcsHash() }}" nonce="{{ _inlineScriptNonce }}" defer></script>
{% endblock %}

The budget check

With hints: 'error', a production build fails when an entry point or a file passes its limit, and the build output names the file. Because the built files are committed and deployed as they are, a build that fails on the developer's machine never reaches the site, which makes the budget a review gate rather than a report someone has to read. Set the limits a little above today's sizes, so that the build fails on growth rather than on the current state, and raise them deliberately, in a commit of their own.

Two failures the budget catches early: a shared module that imports something heavy, so every entry grows at once; and a library imported statically where it should have been loaded with import(). One Twig site in the case studies goes further than an entry per area, with fifteen entries, most of them one per landing-page type.

Go deeper
GuideBundle size GuideWebpack and gulp builds How-toCut a bundle in half with dynamic imports How-toRegister a page-specific JS bundle with a CSP nonce

Was this page helpful?

Your answer goes to the docs team.