Bundle Splitting Strategies

Modern JavaScript applications ship megabytes of code by default. Without bundle splitting, users download, parse, and execute the entire application before seeing anything interactive—regardless of which features they’ll actually use. Bundle splitting transforms monolithic builds into targeted delivery: load the code for the current route immediately, defer everything else until needed. The payoff is substantial—30-60% reduction in initial bundle size translates directly to faster Time to Interactive (TTI) and improved Core Web Vitals.

Bundle splitting reduces initial payload by loading only what's needed for the current route, deferring the rest.

Abstract

Bundle splitting is a build-time optimization that divides application code into separate chunks loaded on demand. The core insight: users access one route at a time, so they should only pay the download cost for that route’s code.

Three fundamental strategies exist, each addressing different optimization goals:

Entry splitting: Create separate bundles per entry point (multi-page apps, micro-frontends). Each entry gets independent dependency resolution.
Route/component splitting: Use dynamic import() to load code when users navigate or interact. The dominant pattern for SPAs.
Vendor splitting: Isolate node_modules into stable chunks. Dependencies change less frequently than application code—separate chunks improve cache hit rates across deployments.

Critical constraints shape implementation:

Static analysis requirement: Bundlers must determine chunk boundaries at build time. Fully dynamic import paths (e.g., import(userInput)) cannot be split.
HTTP/2 sweet spot: 10-30 chunks balance caching benefits against connection overhead. Too few chunks = poor cache utilization; too many = HTTP/2 stream saturation.
Compression effectiveness: Smaller chunks compress less efficiently than larger ones. A 10KB chunk may only compress 50%; a 100KB chunk may compress 70%.
Prefetch/preload timing: Splitting without intelligent loading creates waterfalls. Prefetching predicted routes and preloading critical resources recovers the latency cost.

Build tools handle these trade-offs differently: Webpack’s SplitChunksPlugin offers granular control with complex configuration; Vite/Rollup favor convention over configuration with sensible defaults; esbuild prioritizes speed with simpler splitting semantics.

The Challenge

Browser Constraints

JavaScript execution blocks the main thread. Large bundles create measurable user experience degradation:

Parse time: V8 parses JavaScript at roughly 1MB/second on mobile devices (benchmarked on mid-range Android). A 2MB bundle = 2 seconds of parse time before any code executes.

Execution time: Module initialization (top-level code, class definitions, side effects) runs synchronously. Heavy initialization chains delay interactivity.

Memory pressure: Each loaded module consumes memory for its AST, compiled bytecode, and runtime objects. On memory-constrained mobile devices, loading unused code competes with application state for limited heap.

Performance Targets

Metric	Target	Bundle Impact
LCP (Largest Contentful Paint)	< 2.5s	Initial JS blocks render; smaller bundles = faster LCP
INP (Interaction to Next Paint)	< 200ms	Large bundles increase main thread blocking time
TTI (Time to Interactive)	< 3.8s	Direct correlation with JavaScript payload size

Rule of thumb: Keep initial JavaScript under 100KB gzipped for mobile-first applications. Each additional 100KB adds roughly 1 second to TTI on 3G connections.

Scale Factors

Application Type	Without Splitting	With Splitting	Reduction
Marketing site	50-100KB	20-40KB	40-60%
Dashboard SPA	500KB-1MB	100-200KB	60-80%
E-commerce	1-2MB	200-400KB	70-80%
Complex SaaS	2-5MB	300-600KB	80-90%

Design Paths

Path 1: Route-Based Code Splitting

How it works:

Each route in the application becomes a separate chunk. When users navigate, the router triggers a dynamic import that loads the route’s code on demand.


4 collapsed lines
1
import { lazy, Suspense } from 'react';
2
import { createBrowserRouter, RouterProvider } from 'react-router-dom';
3

4
// Dynamic imports create separate chunks at build time
5
// Webpack names chunks based on the file path or magic comments
6
const Home = lazy(() => import('./pages/Home'));
7
const Dashboard = lazy(() => import('./pages/Dashboard'));
8
const Settings = lazy(() => import('./pages/Settings'));
9
const Analytics = lazy(() =>
10
  import(/* webpackChunkName: "analytics" */ './pages/Analytics')
11
);
12

13
const router = createBrowserRouter([
14
  {
15
    path: '/',
16
    element: (
17
      <Suspense fallback={<PageSkeleton />}>
18
        <Home />
19
      </Suspense>
20
    ),
21
  },
22
  {
23
    path: '/dashboard',
24
    element: (
25
      <Suspense fallback={<PageSkeleton />}>
26
        <Dashboard />
27
      </Suspense>
28
    ),
29
  },
30
  // Additional routes...
31
]);
32

33
function App() {
34
  return <RouterProvider router={router} />;
1 collapsed line
35
}

Why this works:

import() returns a Promise that resolves to the module
Bundlers perform static analysis to identify import boundaries
Each import() call becomes a separate chunk in the build output
React’s lazy() integrates Promises with Suspense boundaries

Framework implementations:

Framework	Mechanism	Configuration
Next.js	Automatic per-page splitting	Zero config; each `pages/*.tsx` is a chunk
React Router	`lazy()` + `Suspense`	Manual setup per route
Vue Router	`() => import('./Page.vue')`	Built into router config
Angular	`loadChildren` in route config	Built into router module
SvelteKit	`+page.svelte` convention	Automatic per-route

Performance characteristics:

Metric	Value
Typical reduction	30-60% of initial bundle
Chunk count	1 per route + shared chunks
Navigation latency	50-200ms for chunk fetch
Caching	Unchanged routes stay cached

Best for:

SPAs with distinct route boundaries
Applications where users typically access a subset of features
Progressive disclosure patterns (landing → dashboard → settings)

Trade-offs:

Navigation delay for first visit to each route
Requires Suspense boundaries for loading states
Shared dependencies across routes need vendor splitting

Real-world example:

Airbnb’s web application uses route-based splitting extensively. Their listing search page, booking flow, and host dashboard are separate chunks. Engineers measured a 67% reduction in initial JavaScript and 20% improvement in TTI after implementing route splitting with prefetching.

Path 2: Component-Level Code Splitting

How it works:

Heavy components within a route are split and loaded on demand—triggered by user interaction or visibility rather than navigation.


3 collapsed lines
1
import { lazy, Suspense, useState } from 'react';
2

3
// Heavy visualization library only loads when chart is rendered
4
const AnalyticsChart = lazy(() =>
5
  import(/* webpackChunkName: "chart" */ './AnalyticsChart')
6
);
7

8
// Rich text editor loads when user clicks "Edit"
9
const RichTextEditor = lazy(() =>
10
  import(/* webpackChunkName: "editor" */ './RichTextEditor')
11
);
12

13
function Dashboard() {
14
  const [showChart, setShowChart] = useState(false);
15
  const [editing, setEditing] = useState(false);
16

17
  return (
18
    <div>
19
      <button onClick={() => setShowChart(true)}>Show Analytics</button>
20

21
      {showChart && (
22
        <Suspense fallback={<ChartSkeleton />}>
23
          <AnalyticsChart data={analyticsData} />
24
        </Suspense>
25
      )}
26

27
      <button onClick={() => setEditing(true)}>Edit Content</button>
8 collapsed lines
28

29
      {editing && (
30
        <Suspense fallback={<EditorSkeleton />}>
31
          <RichTextEditor content={content} />
32
        </Suspense>
33
      )}
34
    </div>
35
  );
36
}

Typical candidates for component splitting:

Component Type	Example Libraries	Typical Size
Rich text editors	Slate, TipTap, Quill	100-300KB
Charting	D3, Chart.js, Recharts	50-200KB
Code editors	Monaco, CodeMirror	500KB-2MB
PDF viewers	pdf.js	400-600KB
Maps	Mapbox, Google Maps	100-500KB
Markdown	marked + highlight.js	50-150KB

Trigger strategies:

User interaction: Load when user clicks a button or tab
Intersection Observer: Load when component scrolls into viewport
Hover intent: Prefetch on hover, load on click
Idle callback: Load during browser idle time


5 collapsed lines
1
import { lazy, Suspense, useEffect, useRef, useState } from 'react';
2

3
const HeavyComponent = lazy(() => import('./HeavyComponent'));
4

5
function LazyOnVisible({ children }: { children: React.ReactNode }) {
6
  const ref = useRef<HTMLDivElement>(null);
7
  const [isVisible, setIsVisible] = useState(false);
8

9
  useEffect(() => {
10
    const observer = new IntersectionObserver(
11
      ([entry]) => {
12
        if (entry.isIntersecting) {
13
          setIsVisible(true);
14
          observer.disconnect();
15
        }
16
      },
17
      { rootMargin: '200px' } // Start loading 200px before visible
18
    );
19

20
    if (ref.current) observer.observe(ref.current);
21
    return () => observer.disconnect();
22
  }, []);
23

24
  return (
5 collapsed lines
25
    <div ref={ref}>
26
      {isVisible ? children : <Placeholder />}
27
    </div>
28
  );
29
}

Trade-offs:

Additional network requests on user interaction
Requires careful loading state design
Can feel slow without prefetching

Path 3: Vendor Splitting

How it works:

Third-party dependencies (node_modules) are extracted into separate chunks. Application code changes frequently; dependencies don’t. Separate chunks maximize cache efficiency.


8 collapsed lines
1
// webpack.config.js
2
module.exports = {
3
  optimization: {
4
    splitChunks: {
5
      chunks: "all",
6
      cacheGroups: {
7
        // Framework chunks (React, Vue, etc.) - very stable
8
        framework: {
9
          test: /[\\/]node_modules[\\/](react|react-dom|scheduler)[\\/]/,
10
          name: "framework",
11
          priority: 40,
12
          enforce: true,
13
        },
14
        // Large libraries get their own chunks
15
        vendors: {
16
          test: /[\\/]node_modules[\\/]/,
17
          name(module) {
18
            // Get library name for chunk naming
19
            const match = module.context.match(/[\\/]node_modules[\\/](.*?)([\\/]|$)/)
20
            const packageName = match ? match[1] : "vendors"
21
            return `vendor-${packageName.replace("@", "")}`
22
          },
23
          priority: 20,
24
          minSize: 50000, // Only split if > 50KB
25
        },
26
        // Shared application code
27
        commons: {
28
          name: "commons",
29
          minChunks: 2, // Used by at least 2 chunks
6 collapsed lines
30
          priority: 10,
31
        },
32
      },
33
    },
34
  },
35
}

Webpack SplitChunksPlugin defaults (v5):

Option	Default	Effect
`chunks`	`'async'`	Only split async imports (change to `'all'` for sync too)
`minSize`	20000	Only create chunks > 20KB
`maxSize`	0	No upper limit (set to enable chunk splitting)
`minChunks`	1	Module must be shared by N chunks to split
`maxAsyncRequests`	30	Max parallel requests for on-demand loads
`maxInitialRequests`	30	Max parallel requests for entry points

Vite/Rollup approach:

1
// vite.config.js
2
export default {
3
  build: {
4
    rollupOptions: {
5
      output: {
6
        manualChunks: {
7
          // Group related dependencies
8
          "vendor-react": ["react", "react-dom", "react-router-dom"],
9
          "vendor-ui": ["@radix-ui/react-dialog", "@radix-ui/react-dropdown-menu"],
10
          "vendor-utils": ["lodash-es", "date-fns"],
11
        },
12
      },
13
    },
14
  },
15
}

Cache efficiency math:

Assume weekly deployments with application code changes each time:

Strategy	Cache Hit Rate	Bandwidth Saved
Single bundle	0% (any change invalidates)	0%
App + vendors	~70% (vendors rarely change)	40-60%
Granular chunks	~85% (only changed chunks reload)	60-80%

Trade-offs:

More HTTP requests (mitigated by HTTP/2)
Configuration complexity
Chunk naming affects cache keys

Path 4: Dynamic Entry Points (Module Federation)

How it works:

Multiple applications share code at runtime. Each application builds independently but can consume modules from other builds dynamically.


5 collapsed lines
1
// Host application webpack.config.js
2
const { ModuleFederationPlugin } = require("webpack").container
3

4
module.exports = {
5
  plugins: [
6
    new ModuleFederationPlugin({
7
      name: "host",
8
      remotes: {
9
        // Load dashboard app's exposed modules at runtime
10
        dashboard: "dashboard@https://dashboard.example.com/remoteEntry.js",
11
        analytics: "analytics@https://analytics.example.com/remoteEntry.js",
12
      },
13
      shared: {
14
        react: { singleton: true, requiredVersion: "^18.0.0" },
15
        "react-dom": { singleton: true, requiredVersion: "^18.0.0" },
16
      },
17
    }),
18
  ],
19
}
20

21
// Remote application webpack.config.js
22
module.exports = {
23
  plugins: [
24
    new ModuleFederationPlugin({
11 collapsed lines
25
      name: "dashboard",
26
      filename: "remoteEntry.js",
27
      exposes: {
28
        "./DashboardWidget": "./src/DashboardWidget",
29
      },
30
      shared: {
31
        react: { singleton: true },
32
        "react-dom": { singleton: true },
33
      },
34
    }),
35
  ],
36
}

Use cases:

Micro-frontends with independent deployment
Platform teams providing shared components
A/B testing different component versions
White-label applications with customizable modules

Trade-offs:

Runtime dependency resolution adds latency
Version conflicts require careful management
Build configuration complexity
Debugging across federated boundaries is harder

Real-world example:

Spotify’s web player uses a micro-frontend architecture where different squads own different features (playlists, search, player controls). Module Federation enables independent deployments while sharing React and design system components.

Decision Matrix

Factor	Route Splitting	Component Splitting	Vendor Splitting	Module Federation
Setup complexity	Low	Low	Medium	High
Build config changes	Minimal	Minimal	Moderate	Significant
Runtime overhead	Low	Low	None	Medium
Cache benefits	Medium	Medium	High	High
Team scalability	Good	Good	Good	Excellent
Best for	SPAs	Heavy components	All apps	Micro-frontends

Decision Framework

Resource Hints: Prefetch and Preload

Splitting code creates smaller initial bundles but introduces latency when loading subsequent chunks. Resource hints recover this latency by loading chunks before they’re needed.

Prefetch vs Preload vs Modulepreload

Hint	Priority	Timing	Use Case
`prefetch`	Lowest	Browser idle time	Next navigation, predicted routes
`preload`	High	Immediate, parallel	Current page critical resources
`modulepreload`	High	Immediate, with parsing	ES modules needed soon

1
<!-- Prefetch: Load during idle for predicted next navigation -->
2
<link rel="prefetch" href="/chunks/dashboard-abc123.js" />
3

4
<!-- Preload: Critical for current page, load immediately -->
5
<link rel="preload" href="/chunks/hero-image.js" as="script" />
6

7
<!-- Modulepreload: ES module with dependency resolution -->
8
<link rel="modulepreload" href="/chunks/analytics-module.js" />

Key difference: modulepreload also parses and compiles the module, making execution instant when needed. preload only fetches.

Webpack Magic Comments

Webpack uses special comments to control chunk behavior:

1
// Named chunk for better cache keys and debugging
2
import(/* webpackChunkName: "dashboard" */ "./Dashboard")
3

4
// Prefetch: load during idle (for predicted navigation)
5
import(/* webpackPrefetch: true */ "./Settings")
6

7
// Preload: load in parallel with current chunk (rare)
8
import(/* webpackPreload: true */ "./CriticalModal")
9

10
// Combined
11
import(
12
  /* webpackChunkName: "analytics" */
13
  /* webpackPrefetch: true */
14
  "./Analytics"
15
)
16

17
// Specify loading mode
18
import(/* webpackMode: "lazy" */ "./LazyModule") // Default
19
import(/* webpackMode: "eager" */ "./EagerModule") // No separate chunk

Prefetch behavior: Webpack injects <link rel="prefetch"> tags after the parent chunk loads. The browser fetches during idle time with lowest priority.

Preload behavior: Webpack injects <link rel="preload"> tags alongside the parent chunk request. Use sparingly—preloading non-critical resources competes with critical ones.

Framework-Specific Prefetching

Next.js (automatic):

1
import Link from 'next/link';
2

3
// Prefetch is automatic on viewport intersection (production only)
4
<Link href="/dashboard">Dashboard</Link>
5

6
// Disable prefetch for rarely-used links
7
<Link href="/admin" prefetch={false}>Admin</Link>
8

9
// Programmatic prefetch
10
import { useRouter } from 'next/navigation';
11
const router = useRouter();
12
router.prefetch('/dashboard');

React Router (manual):


5 collapsed lines
1
import { useEffect } from 'react';
2
import { Link, useLocation } from 'react-router-dom';
3

4
// Prefetch on hover
5
function PrefetchLink({ to, children }: { to: string; children: React.ReactNode }) {
6
  const prefetch = () => {
7
    // Trigger the dynamic import without rendering
8
    if (to === '/dashboard') {
9
      import('./pages/Dashboard');
10
    } else if (to === '/settings') {
11
      import('./pages/Settings');
12
    }
13
  };
14

15
  return (
16
    <Link to={to} onMouseEnter={prefetch} onFocus={prefetch}>
17
      {children}
18
    </Link>
19
  );
20
}
21

22
// Prefetch likely next routes based on current route
23
function usePrefetchPredicted() {
24
  const location = useLocation();
11 collapsed lines
25

26
  useEffect(() => {
27
    if (location.pathname === '/') {
28
      // Users on home often go to dashboard
29
      import('./pages/Dashboard');
30
    } else if (location.pathname === '/dashboard') {
31
      // Dashboard users often check settings
32
      import('./pages/Settings');
33
    }
34
  }, [location.pathname]);
35
}

Intersection Observer Prefetching

Prefetch chunks when their trigger elements become visible:


3 collapsed lines
1
function prefetchOnVisible(selector: string, importFn: () => Promise<unknown>) {
2
  const elements = document.querySelectorAll(selector)
3

4
  const observer = new IntersectionObserver(
5
    (entries) => {
6
      entries.forEach((entry) => {
7
        if (entry.isIntersecting) {
8
          importFn().catch(() => {}) // Prefetch, ignore errors
9
          observer.unobserve(entry.target)
10
        }
11
      })
12
    },
13
    { rootMargin: "200px" },
14
  )
15

16
  elements.forEach((el) => observer.observe(el))
17
  return () => observer.disconnect()
18
}
19

20
// Usage: prefetch analytics chunk when link is visible
21
prefetchOnVisible('[href="/analytics"]', () => import("./pages/Analytics"))

Prefetch Strategy Comparison

Strategy	Latency Improvement	Bandwidth Cost	Implementation
No prefetch	0ms	0	-
Hover prefetch	100-300ms	Low (on interaction)	Manual
Viewport prefetch	200-500ms	Medium (visible links)	IntersectionObserver
Predictive prefetch	300-1000ms	Higher (predicted routes)	Analytics-driven
Aggressive prefetch	Full (no latency)	Highest (all routes)	Simple but wasteful

Bundle Analysis

Identifying Optimization Opportunities

Before optimizing, measure. Bundle analyzers visualize chunk contents, revealing:

Unexpectedly large dependencies
Duplicate modules across chunks
Unused exports (tree-shaking failures)
Missing code splitting opportunities

webpack-bundle-analyzer


3 collapsed lines
1
const BundleAnalyzerPlugin = require("webpack-bundle-analyzer").BundleAnalyzerPlugin
2

3
module.exports = {
4
  plugins: [
5
    new BundleAnalyzerPlugin({
6
      analyzerMode: "static", // Generate HTML file
7
      reportFilename: "bundle-report.html",
8
      openAnalyzer: false,
9
      generateStatsFile: true,
10
      statsFilename: "bundle-stats.json",
11
    }),
12
  ],
13
}

What to look for:

Pattern	Problem	Solution
Single huge chunk	No splitting	Add route/component splitting
Moment.js (500KB)	Full library with locales	Replace with date-fns or dayjs
Lodash (70KB)	Full library	Use lodash-es with tree shaking
Duplicated React	Multiple versions	Resolve alias in config
Large polyfills	Targeting old browsers	Adjust browserslist, use core-js 3

Vite/Rollup Analysis

1
import { visualizer } from "rollup-plugin-visualizer"
2

3
export default {
4
  plugins: [
5
    visualizer({
6
      filename: "bundle-analysis.html",
7
      gzipSize: true,
8
      brotliSize: true,
9
    }),
10
  ],
11
}

Chrome DevTools Coverage

How to use:

Open DevTools → More Tools → Coverage
Click reload button to start instrumenting
Interact with the page
Review unused JavaScript percentage

Interpreting results:

Red = unused code (candidate for splitting or removal)
Green = executed code

Caveat: Coverage shows runtime usage for one session. Code that handles edge cases or error states may appear “unused” but is still necessary.

Budget Enforcement

Set bundle size budgets that fail builds when exceeded:

1
module.exports = {
2
  performance: {
3
    maxAssetSize: 250000, // 250KB per chunk
4
    maxEntrypointSize: 400000, // 400KB for entry points
5
    hints: "error", // Fail build on violation
6
  },
7
}

Recommended budgets:

Application Type	Entry Point	Per Chunk
Marketing site	100KB gzip	50KB gzip
SPA	150KB gzip	75KB gzip
Complex app	250KB gzip	100KB gzip

Build Tool Configuration

Webpack 5


10 collapsed lines
1
const path = require("path")
2

3
module.exports = {
4
  mode: "production",
5
  entry: {
6
    main: "./src/index.tsx",
7
  },
8
  output: {
9
    filename: "[name].[contenthash].js",
10
    chunkFilename: "[name].[contenthash].chunk.js",
11
    path: path.resolve(__dirname, "dist"),
12
    clean: true,
13
  },
14
  optimization: {
15
    splitChunks: {
16
      chunks: "all",
17
      maxInitialRequests: 25,
18
      minSize: 20000,
19
      cacheGroups: {
20
        // React ecosystem - very stable
21
        framework: {
22
          test: /[\\/]node_modules[\\/](react|react-dom|react-router|react-router-dom|scheduler)[\\/]/,
23
          name: "framework",
24
          chunks: "all",
25
          priority: 40,
26
        },
27
        // UI libraries
28
        ui: {
29
          test: /[\\/]node_modules[\\/](@radix-ui|@headlessui|framer-motion)[\\/]/,
30
          name: "vendor-ui",
31
          chunks: "all",
32
          priority: 30,
33
        },
34
        // Remaining node_modules
35
        vendors: {
36
          test: /[\\/]node_modules[\\/]/,
37
          name: "vendors",
38
          chunks: "all",
39
          priority: 20,
40
        },
41
        // Shared app code
42
        common: {
43
          name: "common",
44
          minChunks: 2,
45
          priority: 10,
46
          reuseExistingChunk: true,
47
        },
48
      },
49
    },
50
    // Extract webpack runtime for better caching
51
    runtimeChunk: "single",
52
  },
53
}

Vite 5/6


5 collapsed lines
1
import { defineConfig } from "vite"
2
import react from "@vitejs/plugin-react"
3

4
export default defineConfig({
5
  plugins: [react()],
6
  build: {
7
    target: "es2020",
8
    rollupOptions: {
9
      output: {
10
        manualChunks: (id) => {
11
          // Framework chunk
12
          if (id.includes("node_modules/react")) {
13
            return "framework"
14
          }
15
          // UI library chunk
16
          if (id.includes("node_modules/@radix-ui") || id.includes("node_modules/@headlessui")) {
17
            return "vendor-ui"
18
          }
19
          // Utility libraries
20
          if (id.includes("node_modules/lodash") || id.includes("node_modules/date-fns")) {
21
            return "vendor-utils"
22
          }
23
          // Let Rollup handle remaining splitting
24
        },
25
        // Consistent chunk naming
26
        chunkFileNames: "assets/[name]-[hash].js",
27
        entryFileNames: "assets/[name]-[hash].js",
28
      },
29
    },
30
    // Enable CSS code splitting
31
    cssCodeSplit: true,
32
  },
33
})

esbuild


5 collapsed lines
1
import * as esbuild from "esbuild"
2

3
await esbuild.build({
4
  entryPoints: ["src/index.tsx"],
5
  bundle: true,
6
  // Required for code splitting
7
  splitting: true,
8
  format: "esm", // Required when splitting is enabled
9
  outdir: "dist",
10
  // Chunk naming
11
  chunkNames: "chunks/[name]-[hash]",
12
  entryNames: "[name]-[hash]",
13
  // Minimize output
14
  minify: true,
15
  // Target modern browsers
16
  target: ["es2020", "chrome90", "firefox90", "safari14"],
17
})

esbuild limitations:

No equivalent to Webpack’s splitChunks cacheGroups
Manual chunks require separate entry points
Less granular control over chunk boundaries

Turbopack (Next.js 15+)

Turbopack handles splitting automatically in Next.js:

1
import type { NextConfig } from "next"
2

3
const nextConfig: NextConfig = {
4
  // Turbopack is default in Next.js 15+
5
  // No explicit code splitting config needed
6
  experimental: {
7
    // Fine-tune package imports for tree shaking
8
    optimizePackageImports: ["lodash-es", "@icons-pack/react-simple-icons"],
9
  },
10
}
11

12
export default nextConfig

Automatic optimizations:

Page-level code splitting (each route = separate chunk)
Shared chunks for common dependencies
Automatic prefetching for <Link> components
React Server Components reduce client bundle size

Edge Cases and Gotchas

Dynamic Import Static Analysis

Bundlers analyze import paths at build time. Fully dynamic paths prevent splitting:

1
// WORKS: Bundler creates chunk for each page
2
const pages = {
3
  home: () => import("./pages/Home"),
4
  about: () => import("./pages/About"),
5
  contact: () => import("./pages/Contact"),
6
}
7

8
// WORKS: Template literal with static prefix
9
// Creates chunks for all files matching the pattern
10
const loadPage = (name: string) => import(`./pages/${name}.tsx`)
11

12
// DOES NOT WORK: Fully dynamic path
13
const userPath = getUserInput()
14
import(userPath) // Bundler cannot analyze at build time

Webpack behavior with template literals:

When using import(\./pages/${name}.tsx`), Webpack creates a chunk for every file matching ./pages/*.tsx`. This is called a “context module.”

Circular Dependencies

Circular dependencies can prevent proper chunk splitting:

1
// moduleA.ts
2
import { helperB } from "./moduleB"
3
export const helperA = () => helperB()
4

5
// moduleB.ts
6
import { helperA } from "./moduleA"
7
export const helperB = () => helperA()
8

9
// Bundler may merge these into single chunk to resolve cycle

Detection: Use madge or dpdm to identify circular dependencies:

npx madge --circular src/

Tree Shaking Interaction

Code splitting and tree shaking work together, but order matters:

Tree shaking removes unused exports
Code splitting divides remaining code into chunks

Gotcha: Side effects can prevent tree shaking:

1
// This module has side effects (modifies global state on import)
2
import "./analytics-init" // Always included even if unused
3

4
// Mark as side-effect-free in package.json
5
// "sideEffects": false
6
// Or list specific files with side effects
7
// "sideEffects": ["./src/analytics-init.ts"]

CSS-in-JS and Code Splitting

CSS-in-JS libraries (styled-components, Emotion) may extract CSS that doesn’t split with the component:


3 collapsed lines
1
import styled from "styled-components"
2

3
// These styles may not code-split with the component
4
const StyledButton = styled.button`
5
  background: blue;
6
  color: white;
7
`
8

9
// Lazy load the component - but CSS may be in main bundle
10
const LazyComponent = lazy(() => import("./StyledComponent"))

Solution: Configure SSR extraction or use CSS Modules for components that need reliable code splitting.

SSR Hydration Mismatches

Server-rendered HTML must match client-rendered output. Code-split components that render different content based on browser APIs cause mismatches:


3 collapsed lines
1
import { lazy, Suspense } from 'react';
2

3
// Problem: window is undefined on server
4
const ClientOnlyChart = lazy(() => import('./Chart'));
5

6
function Dashboard() {
7
  // This causes hydration mismatch
8
  return (
9
    <Suspense fallback={<div>Loading...</div>}>
10
      {typeof window !== 'undefined' && <ClientOnlyChart />}
11
    </Suspense>
12
  );
13
}
14

15
// Solution: Use useEffect for client-only rendering
16
function SafeDashboard() {
17
  const [mounted, setMounted] = useState(false);
18

19
  useEffect(() => {
20
    setMounted(true);
21
  }, []);
22

23
  return (
24
    <Suspense fallback={<div>Loading...</div>}>
25
      {mounted && <ClientOnlyChart />}
26
    </Suspense>
27
  );
28
}

HTTP/2 and Chunk Count

HTTP/2 multiplexes requests over a single connection, but has limits:

Browser	Max Concurrent Streams
Chrome	100
Firefox	100
Safari	100

Recommendation: Keep chunk count under 50 for initial load. The sweet spot is 10-30 chunks that balance:

Cache granularity (more chunks = better cache utilization)
Connection overhead (fewer chunks = less overhead)
Compression efficiency (larger chunks = better compression)

Content Hash Stability

Chunk content hashes should only change when content changes. Common pitfalls:

1
// Problem: Import order affects hash
2
import { a } from "./a" // Hash changes if this moves
3
import { b } from "./b"
4

5
// Problem: Absolute paths in source
6
__dirname // Different on different machines
7

8
// Solution: Use deterministic module IDs
9
module.exports = {
10
  optimization: {
11
    moduleIds: "deterministic",
12
    chunkIds: "deterministic",
13
  },
14
}

Real-World Implementations

Vercel/Next.js: Zero-Config Splitting

Challenge: Make code splitting accessible without configuration.

Architecture:

Each file in pages/ or app/ becomes a route chunk automatically
Shared dependencies extracted to _app chunk
Framework code (React, Next.js runtime) in separate chunks
Automatic prefetching via <Link> component

Key decisions:

Convention over configuration: file system = routes = chunks
Aggressive prefetching by default (can disable per-link)
Server Components reduce client bundle by rendering on server

Outcome: Applications using Next.js automatic splitting see 30-50% smaller initial bundles compared to manual Webpack configuration.

Shopify Hydrogen: Commerce-Optimized Splitting

Challenge: E-commerce pages have unique splitting needs—product data, cart, checkout.

Architecture:

Route-based splitting for pages
Component splitting for cart drawer, product variants
Aggressive prefetching for product navigation
Streaming SSR with Suspense boundaries

Key insight: Cart functionality is loaded on interaction, not initial page load. Most users browse products before adding to cart—deferring cart code saves 50KB on initial load.

Google: Differential Loading

Challenge: Support old browsers without penalizing modern ones.

Architecture:

Two builds: ES2020 for modern browsers, ES5 for legacy
<script type="module"> loads modern bundle
<script nomodule> loads legacy bundle
Modern bundle is 20-40% smaller (no polyfills, better compression)

1
<!-- Modern browsers load this (smaller) -->
2
<script type="module" src="/main-modern.js"></script>
3

4
<!-- Only IE11 and old browsers load this -->
5
<script nomodule src="/main-legacy.js"></script>

Trade-off: Doubles build time and artifact storage, but modern users (95%+) get smaller bundles.

Airbnb: Predictive Prefetching

Challenge: Users navigate unpredictably; guessing wrong wastes bandwidth.

Architecture:

Collect navigation patterns via analytics
Build ML model predicting next route from current route
Prefetch predicted routes during idle time
Confidence threshold prevents over-prefetching

Key insight: 80% of navigations follow predictable patterns. Prefetching the top 3 predicted routes covers most users while limiting bandwidth waste.

Outcome: 20% reduction in perceived navigation latency without significant bandwidth increase.

Compression Considerations

Compression vs Chunk Size Trade-off

Smaller chunks compress less efficiently:

Chunk Size	Gzip Reduction	Brotli Reduction
5KB	30-40%	35-45%
20KB	50-60%	55-65%
100KB	65-70%	70-75%
500KB	70-75%	75-80%

Implication: Don’t over-split. A 5KB chunk that could be 2KB gzipped might not be worth the additional HTTP request.

Brotli vs Gzip

Aspect	Gzip	Brotli
Compression ratio	Good (65-70%)	Better (70-75%)
Compression speed	Fast	Slower (3-10x)
Browser support	99%+	96%+
Recommendation	Fallback	Primary

Best practice: Pre-compress assets at build time with Brotli (level 11). Serve Brotli to supporting browsers, gzip to others via content negotiation.

1
// webpack-compression-plugin or vite-plugin-compression
2
{
3
  algorithm: 'brotliCompress',
4
  compressionOptions: { level: 11 },
5
  filename: '[path][base].br',
6
}

Conclusion

Bundle splitting transforms application delivery from “all or nothing” to “what you need, when you need it.” The strategies layer: start with route-based splitting for the largest wins, add vendor splitting for cache efficiency, then apply component splitting for heavy UI elements.

Key principles:

Measure first: Use bundle analyzers to identify actual opportunities, not perceived ones
Route splitting is table stakes: Every SPA should split by route
Vendor chunks maximize caching: Dependencies change less than application code
Prefetching recovers latency: Splitting without prefetching creates navigation delays
HTTP/2 changes the math: More chunks are viable, but don’t over-split (10-30 is optimal)
Compression efficiency decreases with chunk size: Balance splitting benefits against compression loss

The configuration complexity varies by tool—Next.js and Vite provide sensible defaults; Webpack offers granular control at the cost of configuration burden. Choose based on your team’s needs and application constraints.

Appendix

Prerequisites

JavaScript module systems (ESM, CommonJS)
Build tool fundamentals (bundling, minification)
Browser network fundamentals (HTTP/2, caching)

Terminology

Term	Definition
Chunk	A bundle file produced by the build process
Entry point	Initial file that starts application execution
Dynamic import	`import()` syntax that loads modules on demand
Code splitting	Dividing code into chunks loaded separately
Tree shaking	Removing unused exports from bundles
Vendor chunk	Chunk containing third-party dependencies
Magic comment	Build-tool-specific comment affecting bundling behavior
Prefetch	Low-priority fetch for predicted future needs
Preload	High-priority fetch for current page needs

Summary

Bundle splitting reduces initial JavaScript by loading code on demand
Route-based splitting provides 30-60% reduction with minimal configuration
Vendor splitting maximizes cache hit rates across deployments
Prefetch/preload hints recover navigation latency from splitting
Bundle analyzers identify optimization opportunities before and after changes
HTTP/2 enables more chunks, but 10-30 is the practical sweet spot
Compression efficiency decreases with chunk size—don’t over-split

References

Webpack Code Splitting Guide - Official Webpack documentation
Webpack SplitChunksPlugin - Detailed configuration options
Vite Build Options - Rollup-based splitting configuration
Rollup Output Options - Manual chunk configuration
esbuild Code Splitting - esbuild splitting behavior
React.lazy Documentation - Official React code splitting API
Next.js Automatic Code Splitting - Next.js built-in splitting
MDN: Preload - Preload link specification
MDN: Prefetch - Prefetch link specification
MDN: modulepreload - ES module preloading
web.dev: Reduce JavaScript Payloads with Code Splitting - Chrome DevRel best practices
Webpack Module Federation - Micro-frontend architecture
webpack-bundle-analyzer - Bundle visualization tool
rollup-plugin-visualizer - Vite/Rollup analysis

Read more