Code Splitting

Updated September 30, 20263 min read

In short

Code splitting is a technique that breaks a web app's JavaScript into smaller chunks loaded on demand, so the first page load downloads only the code it needs.

What is code splitting?

Without code splitting, a bundler can put an entire application into one large JavaScript file, so a visitor opening the home page also downloads the code for settings, admin screens, and every rarely used feature. Code splitting divides the output into several smaller files, called chunks, and loads each one only when it is needed. The first page becomes interactive sooner because the browser has less code to download, parse, and run.

The main tool is the dynamic import() expression, which returns a promise and tells the bundler to put the imported module into a separate chunk. Frameworks build on it: route-based splitting gives each page its own chunk automatically, and component-level splitting, such as React.lazy() with Suspense, loads heavy widgets like charts, maps, or rich text editors only when they appear. Bundlers also move shared dependencies into common chunks, so the browser can cache them once and reuse them across pages.

Code splitting is like a streaming service that sends one episode at a time instead of making you download the whole season before you can press play. It improves Core Web Vitals such as Largest Contentful Paint and Interaction to Next Paint, especially on phones. The trade-off is extra network requests later, so apps often prefetch the chunks a user is likely to need next, for example when the pointer hovers over a link.

Code splitting is often confused with lazy loading and tree shaking. Code splitting is the build-time step that decides how code is divided into files, while lazy loading is the runtime behavior of fetching something only when it is needed; lazy loading JavaScript depends on code splitting, but images and iframes can be lazy loaded without it. Tree shaking is different again: it deletes unused code entirely, while code splitting keeps all the code and delivers it in pieces.

Key takeaways

Code splitting breaks one large bundle into smaller chunks that load on demand.
Dynamic import() marks where the bundler should start a new chunk.
Route-based splitting gives each page its own code; component-level splitting defers heavy widgets.
Shared chunks let the browser cache common libraries across pages.
Code splitting divides code into pieces; tree shaking removes code that is never used.

Example

Loading a heavy module only when neededjavascript

// Static import: always included in the main bundle
import { renderHeader } from "./header.js";
renderHeader();

// Dynamic import: the bundler puts chart.js in its own chunk,
// downloaded only when the user clicks the button
document.querySelector("#show-chart").addEventListener("click", async () => {
  const { drawChart } = await import("./chart.js");
  drawChart(document.querySelector("#chart"));
});

// In React, the same idea for a component:
// const Editor = React.lazy(() => import("./Editor.jsx"));

Readers ask

What is the difference between code splitting and lazy loading?

Code splitting happens at build time and decides which code goes into which file. Lazy loading happens at runtime and decides when a file is fetched, so lazy loading JavaScript relies on code having been split first.

Does code splitting help SEO?

Indirectly, yes, because faster pages and better Core Web Vitals help rankings and users. Content that search engines should see must not be hidden behind a chunk that only loads after a click.

Can you split code too much?

Yes. Hundreds of tiny chunks add request overhead and can create waterfalls, where one chunk must load before the browser discovers the next. Splitting at routes and at genuinely heavy features is usually the sweet spot.