You open a web app. The page takes four seconds to become interactive. Then you click around, use maybe some features, and close the tab. The browser had already parsed, compiled, and executed 2.4 megabytes of JavaScript to make that happen. Most of it that's because of features that you never touched. But this isn't a theoretical problem. Essentially it's the default behavior of almost every React application that doesn't deliberately address it. To prevent pushing dozens of redundant js files to the user, we use **code splitting**. But to understand how it works and more importantly, how to apply it correctly: We need to start from how a bundler thinks about your code. --- ## 1. How a bundler sees your application When you run `vite build` or `webpack`, the bundler doesn't just concatenate your files. It builds a **** Starting from entry point (`main.tsx`), it follows every static import, then every import inside those files, recursively, until it has visited every module your application depends on. Then it serializes all of that into output files. Here's a simplified project: ```less main.tsx └── App.tsx ├── pages/Home.tsx ├── pages/Dashboard.tsx (imports recharts, d3) ├── pages/AdminPanel.tsx (imports ag-grid, @tanstack/react-table) └── components/Navbar.tsx ``` Without an intervention, the bundler walks this entire tree and outputs: ```typescript dist/ └── bundle.js ← everything, 2.4 MB ``` Every route, every library, every component are packed up, whether the current user will ever see it or not. The bundler is just doing its job: it found everything connected to your entry point, and it bundled it. But the question *code splitting* answers is: *Does everything connected to your entry point need to arrive at the same time?* --- ## 2. Static imports vs dynamic imports This is the mechanical core of code splitting, and it comes down to a single distinction in JavaScript syntax. A **static import** is resolved at compile time. The bundler sees it, follows the edge, and pulls the target module into the same chunk as the source: ```ts import Dashboard from './pages/Dashboard'; // bundler follows this edge ``` A **dynamic import** is a function call that returns a Promise. The bundler sees it too, but instead of inlining the target, it opens a new chunk boundary: ```ts const Dashboard = import('./pages/Dashboard'); // bundler opens a new chunk here ``` That's basically the entire mechanism. `import()` tells the bundler: "this module should live in a separate file, fetched on demand at runtime." Everything the target module imports will follow it into the new chunk, unless it's already been assigned elsewhere. With Vite, the output for a route-split application looks like this: ```less dist/assets/ ├── index-Bx3kP9.js ← app shell + router ~95 KB ├── react-vendor-C7mQR2.js ← react + react-dom ~142 KB ├── Dashboard-Dp8aK1.js ← Dashboard + recharts ~380 KB ├── AdminPanel-Fq2mN7.js ← AdminPanel + ag-grid ~720 KB └── AdminSettings-Gr9xL4.js ~210 KB ``` A user who visits the homepage downloads `index.js` and `react-vendor.js`. That's only 237 KB. So if the user is not authorized yet or basically not admin, `AdminPanel-Fq2mN7.js` won't be downloaded. --- ## 3. Wiring dynamic imports into the component tree: `React.lazy` `import()` gives you a Promise, but react components work synchronous. `React.lazy` bridges that gap: it wraps a dynamic import and makes the result usable as a regular component. ```tsx // Without React.lazy — raw dynamic import, not usable as JSX directly const dashboardModule = import('./pages/Dashboard'); // With React.lazy — returns a component React can render const Dashboard = React.lazy(() => import('./pages/Dashboard')); ``` `React.lazy` expects a function that returns a Promise resolving to a module with a `default` export. When the component is first rendered, React triggers the import, suspends the subtree while the chunk loads, and renders it once the Promise resolves. The suspension mechanism requires `Suspense`: ```tsx import { lazy, Suspense } from 'react'; import { BrowserRouter, Routes, Route } from 'react-router-dom'; // These become separate chunks automatically — no config needed in Vite const Dashboard = lazy(() => import('./pages/Dashboard')); const AdminPanel = lazy(() => import('./pages/admin/AdminPanel')); const AdminSettings = lazy(() => import('./pages/admin/AdminSettings')); // Home is small — static import is fine import Home from './pages/Home'; function App() { return ( }> } /> } /> } /> } /> ); } ``` When a user navigates to `/dashboard`, React attempts to render ``. However, . React suspends the subtree, the nearest `Suspense` boundary renders ``, and the browser fetches `Dashboard-Dp8aK1.js`. Once it arrives, React resumes and renders the component. One `Suspense` boundary at the router level is the right starting point. You can add more granular boundaries later, for example, wrapping a heavy modal separately from the page it lives on. --- ## 4. What actually ends up in each chunk and why it matters Here's something that catches developers off-guard: When you split `AdminPanel` into its own chunk, its *dependencies* come with it. `AdminPanel.tsx` imports `ag-grid-react`. `ag-grid-react` imports its own dependencies. Vite follows every edge from `AdminPanel` and bundles all of them into `AdminPanel-Fq2mN7.js`. ```typescript AdminPanel-Fq2mN7.js ├── AdminPanel.tsx code ~12 KB ├── ag-grid-react ~890 KB └── @tanstack/react-table ~120 KB ────────────────────────────────── ~1022 KB ``` This is actually correct behavior. Users who never visit `/admin` download none of this. The split is working. The problem surfaces when ***multiple chunks share the same library***. Suppose both `Dashboard` and `AdminPanel` import `recharts`: ```typescript Dashboard-Dp8aK1.js ├── Dashboard.tsx code └── recharts + d3 ~420 KB ← full copy AdminPanel-Fq2mN7.js ├── AdminPanel.tsx code └── recharts + d3 ~420 KB ← full copy again ``` A user who visits `/dashboard` and then `/admin` downloads `recharts` twice. The browser can't cache it across chunks because it lives at two different URLs. This is what `manualChunks` is for. --- ## 5. Controlling where libraries live: `manualChunks` `manualChunks` in Vite's config is a function that receives a module ID (its file path) and returns the chunk name it should be assigned to. Vite guarantees that a module only lives in one chunk. ```typescript // vite.config.ts import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [react()], build: { rollupOptions: { output: { manualChunks(id: string) { // React ecosystem — cached separately, never changes between deploys if ( id.includes('node_modules/react') || id.includes('node_modules/react-dom') || id.includes('node_modules/react-router') ) { return 'react-vendor'; } // Chart libraries — only needed on Dashboard if ( id.includes('node_modules/recharts') || id.includes('node_modules/d3') ) { return 'charts-vendor'; } // Admin-specific libraries — only needed on admin routes if ( id.includes('node_modules/ag-grid') || id.includes('node_modules/@tanstack/react-table') ) { return 'admin-vendor'; } } } } } }); ``` The output now looks like this: ``` dist/assets/ ├── index-Bx3kP9.js ← app shell ~95 KB ├── react-vendor-C7mQR2.js ← react, react-dom, router ~142 KB ├── charts-vendor-Hk1mP2.js ← recharts, d3 ~420 KB (one copy) ├── admin-vendor-Jq8nL3.js ← ag-grid, react-table ~1010 KB (one copy) ├── Dashboard-Dp8aK1.js ← Dashboard code only ~8 KB ├── AdminPanel-Fq2mN7.js ← AdminPanel code only ~12 KB └── AdminSettings-Gr9xL4.js ← AdminSettings code only ~6 KB ``` Now compare what each type of user downloads: | User | Files downloaded | Total | | --- | --- | --- | | Visits homepage only | `index` + `react-vendor` | 237 KB | | Visits dashboard | \+ `charts-vendor` + `Dashboard` | 665 KB | | Visits admin | \+ `admin-vendor` + `AdminPanel` | 1.36 MB | | Visits dashboard then admin | `charts-vendor` cached, + `admin-vendor` + `AdminPanel` | 1.36 MB (no duplicate) | The `react-vendor` chunk is also strategically important for caching. , but `react` and `react-dom` don't change between your releases. By isolating them in their own chunk, you ensure that users' browsers cache them across deploys. The content hash in the filename (`react-vendor-C7mQR2.js`) only changes when the library itself updates. --- ## 6. Loading chunks before they're needed: Prefetching Code splitting solves the "don't download what you don't need" problem. Prefetching solves the secondary problem: The perceptible delay when a user navigates to a lazy-loaded route for the first time. When a user clicks a link to `/admin`, three things happen in sequence: 1. The click is registered, 2. the `import()` call fires, 3. the browser makes a network request. On a fast connection this is imperceptible, but on a slow connection or a large chunk, the `Suspense` fallback becomes visible for seconds. Prefetching shifts the network request earlier, to a moment when the user is *likely* to navigate to that route, but hasn't yet. So by the time they click, the chunk is either fully loaded or most of the way there. The two most useful triggers are **after login** and **on hover**: ```tsx // Navbar.tsx import { useEffect } from 'react'; import { Link } from 'react-router-dom'; interface NavbarProps { userRole: 'user' | 'admin'; } function Navbar({ userRole }: NavbarProps) { useEffect(() => { // Admin chunks prefetched after login -> runs once, in the background // Won't compete with initial render; useEffect fires after paint if (userRole === 'admin') { import('./pages/admin/AdminPanel'); import('./pages/admin/AdminSettings'); } }, [userRole]); return ( ); } ``` A few things worth noting here: The `useEffect` approach fires after the component mounts, which means after the initial render and paint have completed. The admin chunks download in the background without competing with the resources needed to show the current page. The `onMouseEnter` approach exploits the \~200–300ms gap between hovering over a link and clicking it. That window is often enough to fetch a small or medium chunk entirely. Calling `import()` on a chunk that's already been fetched is a no-op because browser returns the cached module. So having both `useEffect` prefetch and `onMouseEnter` prefetch for the same chunk is safe, they won't trigger duplicate requests. --- ## 7. A real-world scenario Let's walk through the full picture with the homepage and admin panel use case. The project structure: ``` src/ ├── main.tsx ├── App.tsx ├── pages/ │ ├── Home.tsx ~15 KB — small, static import │ ├── Dashboard.tsx ~8 KB — lazy, pulls charts-vendor │ └── admin/ │ ├── AdminPanel.tsx ~12 KB — lazy, pulls admin-vendor │ └── AdminSettings.tsx ~6 KB — lazy, pulls admin-vendor └── components/ └── Navbar.tsx ``` `App.tsx`: ```tsx import { lazy, Suspense } from 'react'; import { BrowserRouter, Routes, Route } from 'react-router-dom'; import Home from './pages/Home'; import Navbar from './components/Navbar'; import { useAuth } from './hooks/useAuth'; const Dashboard = lazy(() => import('./pages/Dashboard')); const AdminPanel = lazy(() => import('./pages/admin/AdminPanel')); const AdminSettings = lazy(() => import('./pages/admin/AdminSettings')); function App() { const { user } = useAuth(); return ( }> } /> } /> {user?.role === 'admin' && ( <> } /> } /> )} ); } ``` Notice the conditional route rendering. Admin routes aren't registered for non-admin users at all. There's nothing to navigate to, nothing to prefetch, no accidental chunk request. **What a regular user experiences:** 1. Browser fetches `index.js` + `react-vendor.js` — 237 KB total. 2. App renders, `Home` displays immediately (static import, already in `index.js`). 3. User navigates to `/dashboard` -> `charts-vendor.js` + `Dashboard.js` fetched (428 KB). 4. `admin-vendor.js` and the admin chunks never touch the network. **What an admin user experiences:** 1. Same initial 237 KB. 2. After login, `useEffect` in `Navbar` fires -> `AdminPanel.js`, `AdminSettings.js`, and their vendor chunk begin downloading in the background. 3. User sees the dashboard, navigates around. 4. User clicks the Admin link -> chunk is already cached. No spinner. Instant render. The admin's total download is larger, but they only pay for it once, cached across sessions, and it doesn't slow down their initial load. --- ## 8. When not to split Code splitting adds a network round trip. For small modules, that cost outweighs the benefit. A `

Writing