Code Splitting
The boot set is everything a user downloads and evaluates before the app renders: on web the main
entry plus the app chunk group, measured in gzip because it is served over the wire; on desktop the
renderer's initial chunks, measured raw because the asar ships them uncompressed. Every static import
reachable from the composition root lands there, including thunks, middlewares and providers that only
one feature uses. Routes are already split on web
(webComponents.ts); the rules below are about
everything else.
Prefer a dependency the bundler can shrink
Before adding an external package, look it up in a tool such as Bundlephobia: raw (minified) and gzip size, whether it is tree-shakeable and whether it has side effects. Always prefer a package that:
- Ships ES modules, not CommonJS. Tree-shaking needs static
import/export; expect a CommonJS package to land in the bundle whole. - Is tree-shakeable: unused exports are removed during bundling, so the cost is what is imported, not what the package publishes.
- Has no side effects, or at least declares
sideEffectsin itspackage.json. Without the field the bundler keeps every module the imported entry pulls in, used or not.
The tool measures the package alone; the production build below shows what it adds to the boot set.
Split what a user may never reach, not what first paint needs
A library or feature behind a user action or a feature gate is a candidate: a QR scanner, charts, markdown, an SDK that one provider or thunk calls, modals, generated schemas. What the first screen renders unconditionally is not: lazy loading the boot spinner only adds a white screen and one more round trip.
- A dependency the boot path reaches synchronously cannot be split; replace it with something
already in the boot set: a second validation library with
zod, a head manager with React 19<title>hoisting, a Node polyfill with@noble/*. - Bytes leave only with the last importer. A module stays in the boot set while any static path
to it remains: a barrel re-export (
export *of a chart component keepsrechartsin the boot set), another consumer of the same library, or a workspace package without asideEffectsfield. Trace every static path before writingimport(); a split with a leak left behind is a no-op. - Desktop keeps its route map static (desktopComponents.ts, note 2): lazy routes there showed dashboard content ~380 ms later on first visit. Split libraries and modals on desktop, not pages.
Put import() at the point of use and keep the public API
The boundary belongs inside the function that uses the dependency, in the module that owns it — the
provider class, util, client module or DI composition root — after any cheap early return, so no caller
changes. await import() at module scope is not a split: it runs when the module is evaluated, which
for a boot module is at boot. Types stay static as import type. A function that becomes async returns
the Result its callers already handle instead of throwing; a DI contract the load crosses is widened
to carry the failure.
// bad - a static import puts the whole SDK in the boot set for the one thunk that uses it
import { buildApprovedNamespaces } from '@walletconnect/utils';
export const sessionProposalApproveThunk = createThunk(type, () => {
const approvedNamespaces = buildApprovedNamespaces({ proposal, supportedNamespaces });
});
// good - walletConnectThunks.ts - imported inside the thunk, right before it is used
export const sessionProposalApproveThunk = createThunk(type, async () => {
const { buildApprovedNamespaces } = await import('@walletconnect/utils');
const approvedNamespaces = buildApprovedNamespaces({ proposal, supportedNamespaces });
});
For a component, move the heavy part into its own module and keep everything around it — the sized
box, tabs, buttons, the form cell — eager, so layout and controls survive both loading and failure.
Suspense sits at the render site, after the gate (useSelector, the open check): a lazy component
rendered unconditionally fetches on every boot. Drop the raw component from the barrel and mark it "do
not use directly"
(TransactionsGraph.tsx),
and move a provider that exists only for the lazy dependency across the boundary with it.
// good - consumers render the loader, the graph and its chart library arrive in their own chunk
const TransactionsGraph = lazy(() =>
import('./TransactionsGraph').then(module => ({ default: module.TransactionsGraph })),
);
export const TransactionsGraphLoader = (props: TransactionsGraphProps) => (
<Suspense fallback={null}>
<TransactionsGraph {...props} />
</Suspense>
);
Keep import() statically analyzable
- Destructure at the
await import(), or name the exports withwebpackExportswhen the promise is passed around. A helper that returns the whole namespace keeps every export in the chunk: one SDK shipped its unused uploader and downloader that way, +7.8 KB gzip. - Never import a barrel and index it at runtime.
import('date-fns/locale')plusmodule[lang]keeps all 96 locales (~2 MB) instead of the 16 supported; a map of literalimport('date-fns/locale/cs')calls does not (useDateFnsLocale.ts). Files in one directory may use a template literal with/* webpackChunkName: "translations/[request]" */(useIntlMessages.ts). - Group many small boundaries with
webpackChunkNameso a feature does not fragment into a chunk per component: pages share their area's group ("wallet","settings"). The name never reaches the filename (chunkFilenameisjs/[id].[contenthash:8].jsin createBaseConfig.ts); identify a chunk by what it contains.
Cache the load, never the failure
A loader keeps the in-flight promise so concurrent callers share one download, and clears it on rejection so the next call downloads again.
// good - one client per app, a failed load is not cached
clientPromise ??= createClient().catch(error => {
clientPromise = null;
throw error;
});
- A react-query
queryFnmust reject. Catching theimport()and resolving a fallback caches the fallback for the session understaleTime: Infinity; rejecting leaves retry andrefetchOnReconnectto react-query while the consumer rendersdata ?? fallback(useDateFnsLocale.ts). React.lazycaches a rejection for the life of that component. A retry needs a freshlazy(): pin the wrapper per mount withuseState(() => Lazy)and re-arm the module-level one from auseEffectof the stand-in the loader resolves on failure. Re-arming inside the loader'scatchre-renders the uncommitted tree every time a load settles: 67 chunk requests in 269 ms on one mount. A plainlazy()with no retry leaves the component dead until reload.- A fire-and-forget preload swallows its own rejection (
preload().catch(() => undefined)); the first real use reports the failure.
// good - PlainTextMarkdown.tsx - the stand-in the loader resolves when the chunk fails to load
export type LazyMarkdownProps = Options & { onLoadFailure: () => void };
export const PlainTextMarkdown = ({ children, onLoadFailure }: LazyMarkdownProps) => {
// An effect runs after the commit, so the retry is armed for the next mount, not this one
useEffect(() => {
onLoadFailure();
}, [onLoadFailure]);
return <PlainText>{children}</PlainText>;
};
// good - Markdown.tsx - one download per mount, the next mount retries a failed load
const loadReactMarkdown = (): Promise<{ default: ComponentType<LazyMarkdownProps> }> =>
import(/* webpackExports: ['default'] */ 'react-markdown').catch(() => ({
default: PlainTextMarkdown,
}));
let ReactMarkdown = lazy(loadReactMarkdown);
export const Markdown = (options: Options) => {
const [MountedReactMarkdown] = useState(() => ReactMarkdown);
// Never called from the loader: a fresh lazy created there downloads again right away
const rearmReactMarkdown = () => {
if (ReactMarkdown === MountedReactMarkdown) {
ReactMarkdown = lazy(loadReactMarkdown);
}
};
return (
<Suspense fallback={null}>
<MountedReactMarkdown {...options} />
</Suspense>
);
};
A failed chunk follows the existing error contract
Where callers expect a Result, return its error variant; where they already handle a rejection,
reject; a component degrades in place (plain text, a disabled control of the same size). A bare
rejection where callers never handled one leaves the UI stuck: a click that does nothing, a modal that
never closes. A component that must mount in the same commit as the action opening it stays eager: a
modal that calls preserveModal() when it mounts is closed by CLOSE_UI_WINDOW if it mounts one
download later.
The fallback keeps the size, a preload keeps the timing
fallback={null}inside an always-rendered wrapper when nothing rendered during loading before; a placeholder of the final size, computed from the content, when the lazy part has one (a calendar's rows for the month and locale, a control's height). A skeleton that duplicates the component's own loading state shows, disappears and shows again.- User-activation work must not wait for a download. An OAuth popup or a clipboard write started by
a click is blocked when the chunk is fetched after the click: preload when the surface offering the
action mounts. A synchronous consumer preloads at composition. A chunk that post-processes a network
response starts alongside it:
Promise.all([fetchConfig(), preloadParser()]).
Platforms differ
- Connect core runs in the desktop main process, so a split inside it changes only web; desktop has no lazy routes, so a component already inside a lazy web route still saves on desktop. Report both.
suite-nativeships one Metro bundle in release, soimport()in shared code buys nothing there, and in development a package that resolves to.cjsfails at startup with "Requiring unknown module" unlesscjsAsyncChunkPackagesin metro.config.js lists it.@metro-ignoreonly hides the failure. Check the native dev build for anyimport()added to shared code.
Prove it with a production build
- Build both apps in production and compare the boot set and all JS, raw and gzip, against
develop(yarn workspace @suite-app/web-app analyze,yarn suite:build:web:preview). A split is relocation, not deletion: expect +1–2 KB gzip of loader overhead per chunk, and read more as lost tree-shaking. A dependency shared between the boot chunk and a lazy chunk is duplicated into every lazy chunk that needs it once it leaves the boot set. - Boot membership comes from chunk groups (web: the
mainentrypoint plus theappgroup; desktop: themainentrypoint), never from a module id grepped out of a chunk: a boot chunk referencing an id is whatimport()compiles to. The vite dev server does not reproduce the production graph. - A static import anywhere in the graph defeats the split silently. Delay the lazy module with a
setTimeoutin the loader and watch whether the library loads before it. - Unit tests mock the module to throw (
jest.doMockunderjest.isolateModulesAsyncor afterjest.resetModules()), assert the error contract and that the next call loads again; a lazy component loads once per mount across re-renders and again on the next mount. For a map of loaders ('ja-JP': () => import('date-fns/locale/ja')), test that every key loads the module it names: all loaders share one type, so'ja-JP'pointing at the Spanish locale still compiles. Then hide the chunk file of the production build, confirm the degraded behaviour, restore it and confirm the feature loads again without a page reload.
Related skills
- Long and non-essential tasks — when to defer a preload or background work.
- React hooks — memoization, dependency arrays, render loops.
- Packages — workspace manifests and dependency declarations.