Code Splitting Strategies

Learn how to break a monolithic JavaScript bundle into on-demand chunks — reducing initial load time dramatically without sacrificing functionality — and build the splitting discipline that keeps bundles lean as your application grows.

The Bundle That Ate the Loading Screen

When Figma's engineering team published a breakdown of their web editor bundle in 2019, the canvas rendering engine alone was over 700KB gzipped. Loading the app on a mid-range laptop over home broadband took north of eight seconds before anything was interactive. Their response was not to rewrite the engine — it was to split the bundle so aggressively that the critical path to "editor is ready" shrunk from 700KB+ to under 200KB, with the rest streaming in the background while the user was already working.

Code splitting is the practice of dividing your JavaScript bundle into smaller chunks that load on demand rather than all at once. The total code hasn't changed. But the browser downloads what the user actually needs right now — and defers everything else until it's required. The difference between "load everything upfront" and "load what you need when you need it" is the difference between an 8-second loading screen and a 1.4-second Time to Interactive.

The PixelForge Performance team inherited a 680KB gzipped initial bundle. Users visiting the login page were downloading the full canvas editor, the admin panel, the billing dashboard, and the onboarding wizard before seeing a single interactive element. This lesson documents exactly what they did about it.

How Code Splitting Works Under the Hood

Code splitting is a coordination between your bundler and the browser. Vite, webpack, and Rollup analyse your module graph at build time. When they encounter a dynamic import — import('./HeavyModule') — they treat it as a split point. Everything reachable only through that dynamic import gets emitted as a separate chunk file. At runtime, when the dynamic import executes, the browser fetches that chunk over the network the first time, then from cache on subsequent visits.

A dynamic import returns a Promise. The browser handles it asynchronously — fetches the chunk, parses it, evaluates it, and resolves the promise with the module's exports. This is why every code-split boundary needs a loading state: the user sees something between "chunk requested" and "chunk ready." React's Suspense boundary is the standard mechanism for managing that loading state without per-component loading logic scattered everywhere.

The Three Splitting Strategies — Route, Component, Vendor

Not all split points are equal. Route-level splits work differently from component-level splits, which work differently from vendor chunk separation. Understanding when to apply each strategy is what separates disciplined splitting from adding dynamic imports everywhere and creating a waterfall of 40 sequential network requests on first load.

Route-Level Splitting in Practice

Route splitting is the highest-leverage technique because routes are natural, user-initiated boundaries. A user navigating to /settings has already decided to go there — the 200–300ms chunk fetch is invisible inside the normal navigation latency. But the 200KB of settings code that was previously loading on every page visit is now deferred entirely for users who never open settings.

// WHAT: PixelForge router — route-level splitting with React.lazy + Suspense
// Before: all routes imported statically → 680KB initial bundle
// After: each route is a separate chunk → 84KB initial bundle

import { lazy, Suspense } from 'react';
import { Routes, Route } from 'react-router-dom';

// Each lazy() call creates a separate chunk at build time.
// Vite emits: chunk-dashboard.a8f3.js  (92KB gzipped)
//             chunk-editor.b2c1.js     (188KB gzipped)
//             chunk-settings.d9e7.js   (34KB gzipped)
//             chunk-billing.c3a5.js    (28KB gzipped)
//             chunk-onboarding.f2d4.js (41KB gzipped)
const DashboardPage  = lazy(() => import('./pages/DashboardPage'));
const EditorPage     = lazy(() => import('./pages/EditorPage'));
const SettingsPage   = lazy(() => import('./pages/SettingsPage'));
const BillingPage    = lazy(() => import('./pages/BillingPage'));
const OnboardingPage = lazy(() => import('./pages/OnboardingPage'));

// Skeleton fallback — approximates the loaded layout
function PageSkeleton() {
  return (
    <div style={{ padding: '32px', maxWidth: '1200px', margin: '0 auto' }}>
      <div style={{ height: 32, width: '40%', background: '#e2e8f0',
        borderRadius: 8, marginBottom: 24 }} />
      <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr 1fr', gap: 16 }}>
        {[...Array(6)].map((_, i) => (
          <div key={i} style={{ height: 140, background: '#e2e8f0',
            borderRadius: 12 }} />
        ))}
      </div>
    </div>
  );
}

export function AppRouter() {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <Routes>
        <Route path="/dashboard"        element={<DashboardPage />} />
        <Route path="/editor/:canvasId" element={<EditorPage />} />
        <Route path="/settings/*"       element={<SettingsPage />} />
        <Route path="/billing"          element={<BillingPage />} />
        <Route path="/onboarding"       element={<OnboardingPage />} />
      </Routes>
    </Suspense>
  );
}

// Prefetch on hover — loads the next likely chunk before the user clicks.
// Fire-and-forget dynamic import: the browser caches the chunk response
// so when the route loads, the chunk is already available.
function NavLink({ to, label }) {
  const prefetch = () => {
    if (to === '/editor')   import('./pages/EditorPage');
    if (to === '/settings') import('./pages/SettingsPage');
  };
  return <a href={to} onMouseEnter={prefetch}>{label}</a>;
}

Component-Level Splitting — Inside a Route

Route splitting handles the gross structure. But within a single route, some components carry heavy third-party libraries used by only a fraction of sessions. The PixelForge editor route is 188KB gzipped after route splitting — but inside that chunk lives the export-to-PDF feature, which bundles pdf-lib (98KB gzipped). Only 8% of sessions ever open the export modal. The other 92% download 98KB of PDF library they will never use on that visit.

Component-level splitting moves that 98KB behind a conditional boundary — it only loads when the user actively opens the modal. This is the correct model for any feature that is genuinely optional during a session: load the code only when the user has proven they intend to use the feature.

// WHAT: PixelForge ExportModal — component-level splitting
// pdf-lib (98KB gzipped) loads only when the modal opens
// 92% of sessions never trigger this download

import { lazy, Suspense, useState } from 'react';

// A static import here would include pdf-lib in the editor chunk always:
// import ExportModal from './ExportModal';  ← adds 98KB to every session

// Lazy import — pdf-lib enters the chunk graph only when ExportModal is requested
const ExportModal = lazy(() => import('./ExportModal'));

function ExportButton() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button
        onClick={() => setIsOpen(true)}
        className="toolbar-btn"
      >
        Export to PDF
      </button>

      {/* Suspense scoped to the modal — fallback renders inside modal container */}
      {isOpen && (
        <Suspense fallback={<ModalSkeleton />}>
          <ExportModal onClose={() => setIsOpen(false)} />
        </Suspense>
      )}
    </>
  );
}

function ModalSkeleton() {
  return (
    <div style={{
      position: 'fixed', inset: 0,
      background: 'rgba(15,23,42,0.5)',
      display: 'flex', alignItems: 'center', justifyContent: 'center',
      zIndex: 9999
    }}>
      <div style={{
        background: '#fff', borderRadius: 16,
        padding: '32px', width: 480, maxWidth: '90vw'
      }}>
        <div style={{ height: 24, width: '55%', background: '#e2e8f0',
          borderRadius: 6, marginBottom: 20 }} />
        <div style={{ height: 100, background: '#f8fafc',
          borderRadius: 10, marginBottom: 16 }} />
        <div style={{ display: 'flex', justifyContent: 'flex-end', gap: 12 }}>
          <div style={{ height: 38, width: 80, background: '#e2e8f0', borderRadius: 8 }} />
          <div style={{ height: 38, width: 120, background: '#7c3aed', borderRadius: 8 }} />
        </div>
      </div>
    </div>
  );
}

// Inside ExportModal.tsx the heavy library is a regular static import.
// It only runs when the ExportModal chunk is evaluated — which only
// happens when the modal is opened for the first time in a session.
// import { PDFDocument, rgb, StandardFonts } from 'pdf-lib';

Vendor Chunk Strategy — Making Cache Work Across Deploys

Every time you deploy a new version of PixelForge, the content hash of your application chunks changes. Users must download the new chunks. But React itself hasn't changed. ReactDOM hasn't changed. Lodash hasn't changed. If those libraries are bundled into your application chunks, every deploy forces users to re-download them — even though they're identical to the previous version.

Vendor chunk separation solves this by emitting all stable third-party libraries into a separate chunk with its own content hash. That hash only changes when a library version changes. A user who visited PixelForge three weeks ago has the vendor chunk cached with a one-year max-age. When a new PixelForge feature deploys, the vendor chunk hash hasn't changed — the browser serves it from cache instantly, saving the full 43KB download on every returning user's session.

Knowing What to Split — The Bundle Analyser

Code splitting decisions should be data-driven, not intuition-driven. The question "what should I split?" is answered by the bundle analyser — a treemap visualisation of exactly which modules contribute how many bytes to which chunks. Every front end team should run this analysis before the first splitting decision and after each major dependency addition.

For Vite projects, rollup-plugin-visualizer generates an interactive treemap as part of the build. For webpack, webpack-bundle-analyzer serves the same purpose. Both show the same information: every module in your bundle, its size, and which chunk it lives in. In five minutes of exploring the treemap, the PixelForge Performance team identified three libraries that accounted for 41% of the initial bundle — none of which needed to be in the initial chunk at all.

Quiz