Section Chunking

Section chunking splits each section into its own JavaScript bundle. The theme engine then loads only the chunks that the current page uses. This reduces the first-load bundle size of a storefront page.

Section chunking is optional. A theme that does not enable it keeps the single-bundle behaviour.

Prerequisites

• A React theme.
• An FDK CLI version that supports section chunking. Run fdk --version and compare it with the version that your platform release notes give.

Step 1: Add the packages

Add these two packages to the package.json file of the theme:

{
  "dependencies": {
    "@loadable/component": "^5.16.4"
  },
  "devDependencies": {
    "@loadable/babel-plugin": "^5.16.1"
  }
}

Step 2: Enable the feature flag

Add the fdk_feature block to the package.json file of the theme:

{
  "fdk_feature": {
    "enable_section_chunking": true
  }
}

Step 3: Add the Babel plugin

Add @loadable/babel-plugin to the Babel presets in webpack.config.js:

rules: [
  {
    test: /\.(ts|tsx)$/,
    exclude: /node_modules/,
    use: [
      {
        loader: "babel-loader",
        options: {
          presets: [
            ["@babel/preset-env", { targets: "defaults" }],
            "@babel/preset-react",
            "@babel/preset-typescript",
            "@loadable/babel-plugin",
          ],
        },
      },
    ],
  },
];

Step 4: Add a default export to each section

Without chunking, a section file exports Component and settings as named exports. With chunking, the section file must also have a default export.

import React from "react";
import ImageBanner from "../components/image-banner-section/image-banner.jsx";

export function Component({ props }) {
  const { bannerImage } = props;
  return bannerImage?.value ? <ImageBanner bannerImage={bannerImage} /> : null;
}

export const settings = {
  label: "Banner Image",
  props: [
    {
      id: "bannerImage",
      label: "Link of the Banner Image to set",
      type: "text",
      default: "",
    },
  ],
};

export default Component; // Required for section chunking

Keep the settings object as a literal at the top level of the file. The CLI reads the object statically. The CLI cannot read a settings object that a function builds at runtime.

Section file name rules

The CLI validates every section file name. A file name that breaks a rule fails the build.

Rule	Example
Use kebab case	image-banner.jsx
Do not use an underscore, a digit, or an extra dot	image_banner.jsx is not valid
Do not use the word section or sections	banner-section.jsx is not valid

The current CLI reads chunked settings from .jsx files only. Verify CLI support before you move a section to .tsx.

Generated section registry

The CLI writes theme/sections/index.js. The file maps each section name to a loadable component.

import loadable from "@loadable/component";
import React from "react";

const AboutBrandSectionChunk = loadable(
  () => import(/* webpackChunkName:"AboutBrandSection" */ "./about-brand")
);
const CategoryBannerSectionChunk = loadable(
  () => import(/* webpackChunkName:"CategoryBannerSection" */ "./category-banner")
);

const getbundle = (type) => {
  switch (type) {
    case "about-brand":
      return (props) => <AboutBrandSectionChunk {...props} />;
    case "category-banner":
      return (props) => <CategoryBannerSectionChunk {...props} />;
    default:
      return null;
  }
};

export default {
  "about-brand": {
    ...AboutBrandSectionChunk,
    Component: getbundle("about-brand"),
  },
  "category-banner": {
    ...CategoryBannerSectionChunk,
    Component: getbundle("category-banner"),
  },
};

The CLI owns this file. Do not add permanent code to it. The next build replaces your changes.

Commit the generated registry after you add, rename, or delete a section. A local serve command can run its first build before it refreshes the registry. A stale registry then hides the new section.

Workflow

1. Add or change the section source file.
2. Confirm the file name and the exports.
3. Refresh the section registry and assets.json.
4. Run the package command of the theme.
5. Run the package command again if the first run changed the registry.
6. Run the serve command.
7. Open the section in a browser and confirm the result.

Troubleshooting

Symptom	Check
The build reports an invalid file name	The file name uses kebab case and no restricted word
The theme editor shows no settings for the section	The settings object is a top-level literal
The section renders as an empty block	The section file has a default export
The build fails inside loadable code	The two @loadable packages and the Babel plugin
A local build does not show a new section	The committed section registry is current

Verification

Build the theme and look for one chunk file for each section in the .fdk/dist/ directory. Open a storefront page and confirm that the browser downloads only the chunks of that page. Confirm that server-side rendering hydrates the page without a console error.

Chunking reduces the bytes that the browser downloads. It does not reduce layout shift, and it does not reduce main-thread time on its own. Read Performance Overview for the rules that control those.