Fixing Oversized JavaScript Bundles

Why bundle size costs more than download time

It is tempting to think of a large script as a bandwidth problem that compression and a fast CDN will solve. Compression does shrink the transfer, often to a quarter or less of the original, but the browser decompresses it again before doing anything with it. What the phone has to work through is the full, uncompressed code.

That work happens in stages, and most of it is on the main thread, the same thread that responds to taps and draws the page:

1. Download. Affected by transfer size, the number of requests and whether the file is cached.
2. Parse and compile. The JavaScript engine reads the text and turns it into something it can run. The cost grows with the amount of code, whether or not that code is ever called.
3. Execute. Top-level code in every module runs straight away: registering components, building lookup tables, setting up listeners. A large bundle usually means a lot of this start-up work.

So a 400 KB bundle that compresses to 110 KB still means 400 KB of parsing and whatever start-up work those modules do. On a developer laptop this passes unnoticed. On the kind of phone many customers actually use, it shows up as long tasks during load and a sluggish first tap, which is why heavy bundles tend to appear alongside poor Interaction to Next Paint.

Finding out what is in the bundle

You cannot trim what you cannot see. Three views together give a full picture.

1. The checker and the Network panel: what each page loads

The JavaScript Checker lists every script the page loads with its size and the time spent parsing and running it. Run it on each main template: home, category or listing, product or article, basket, and any logged-in dashboard. Note which files are shared by every template and which are specific to one. In Chrome DevTools, the Network panel filtered to JS shows the same files with transferred and resource sizes side by side.

2. A bundle analyser: what each file is made of

An analyser reads your build output and draws a treemap, one rectangle per module, sized by bytes. The biggest rectangles are where the savings are.

3. The Coverage panel: what actually runs

Open DevTools, press Ctrl+Shift+P (Cmd+Shift+P on a Mac), type "Coverage" and start recording, then reload the page. Each script gets a bar showing how many bytes were used during the session. A file that is 70 per cent unused on the home page is a strong candidate for splitting. Coverage only counts what ran during your test, so click through the menu, search and basket before trusting the number.

The usual reasons a bundle is too big

Splitting code with dynamic imports

A static import at the top of a file puts that module into the same bundle. A dynamic import() tells the build tool to create a separate chunk that is fetched only when the line runs. That one change is the main lever for cutting what each page loads.

// Before: the chart library is in the main bundle for every page
import { renderChart } from './charts.js';

// After: fetched only when the reports tab is opened
document.querySelector('#reports-tab').addEventListener('click', async () => {
  const { renderChart } = await import('./charts.js');
  renderChart(document.querySelector('#chart'));
});

Good candidates for their own chunk are routes most visitors never reach, dialogs and drawers, editors, maps, charts, video players, and anything behind a login. Poor candidates are the code for the first screen, which you want as early as possible, and tiny modules, where a separate request costs more than it saves.

Two refinements keep split code feeling instant:

• Warm the chunk on intent. Start the import when a pointer moves over the button or the element scrolls near the viewport, so the download is under way before the click.
• Preload chunks the next page certainly needs with <link rel="modulepreload">, which fetches and parses a module ahead of time without running it.

Tree shaking: letting the build remove dead code

Tree shaking is the build tool dropping exports nobody imports. It only works when the code is written as ES modules and the tool can be confident that removing a module has no side effects. Three things commonly stop it:

1. CommonJS packages. Code using require and module.exports cannot be analysed reliably, so the whole package is kept. Many libraries publish an ES module version, sometimes under a different name ending in -es.
2. Importing everything. import * as utils or a default import of a large object pulls in the lot. Import the named functions you use.
3. Missing side-effect information. If your own package or a library lacks a sideEffects field in package.json, the bundler has to assume importing a file might change something globally and keeps it.

{
  "name": "example-shop-ui",
  "type": "module",
  "sideEffects": ["*.css", "./src/polyfills.js"]
}

Listing only the files that genuinely do something on import (stylesheets, polyfills) lets the bundler drop every other unused module. Get this wrong and a stylesheet or a registration file silently disappears from the build, so test after changing it.

Build targets and polyfills

Build tools transform modern syntax and add polyfills for the browsers you tell them to support. A target list written years ago can force the build to rewrite classes, async functions and optional chaining into longer older code, and to include polyfills every current browser already has.

Check the browserslist entry in package.json, the build.target setting in Vite, or the target in your Babel or TypeScript configuration. Compare it with your analytics: if almost nobody visits in a browser that lacks ES module support, there is little reason to transform code for it. Also look for polyfill libraries imported wholesale at the entry point and replace them with targeted polyfills or none at all.

The fix, step by step

Edge cases and trade-offs

• Too many tiny chunks. Over-splitting creates waterfalls, where one chunk has to load before the browser discovers the next. If the Network panel shows long chains of small requests, merge chunks that are always used together.
• Cache busting on every release. If a change to one line renames the main bundle, returning visitors download it all again. Put stable vendor code in its own chunk with a content hash so it stays cached between releases.
• Third-party scripts are not in your bundle. Analytics, chat and advertising code loads separately and will not appear in the treemap. The checker lists them with their cost, and the third-party tags guide covers how to govern them.
• Smaller but still slow. A modest bundle can still run one heavy function on load. If execution time stays high after the size drops, the problem is long tasks rather than weight; profile it in the Performance panel.
• Server-rendered frameworks. Rendering HTML on the server does not remove the JavaScript needed to make it interactive. Check how much of each component really needs to run in the browser.

Keeping the bundle small

• Review dependencies before adding them. Check a package's installed and bundled size before merging it, and ask whether a native API does the job.
• Keep the analyser report in each build. Save the treemap as a build artefact so anyone can see what changed when the size jumps.
• Budgets per route, not one global number. A shared total hides one page quietly doubling.
• Review targets once a year. Browser support moves on; your build settings should too.
• Test on a real mid-range phone or with CPU throttling in DevTools, so the cost of parsing is visible to the people making the decisions.