Guides

How to shrink your JavaScript bundle — 6 steps and the command to start with

Illustration: pulling the excess out of an overstuffed suitcase

The site opens sluggishly and you've already compressed the images. So it's JavaScript's turn: downloading it isn't enough — the browser also has to parse and run it, and the page ignores taps the whole time.

Good news: it's almost always two or three specific dependencies, not "the code in general". Below is how to find them and what to do about them. Order matters: measure first, cut second.

Step 1. Get the real number

The file size from npm run dev means nothing: in development the bundler deliberately skips optimisation. You have to measure the production build.

npm run build

The bundler prints a list of files and their sizes — often in two columns: raw and compressed. Write both numbers down; you'll compare at the end.

A rough marker: if all your JavaScript fits into 100–150 KB compressed, you're fine and can stop reading. Past that it gets interesting.

Step 2. Look at what it's made of

This is the key step, and it's one command. A build map draws rectangles: the bigger the area, the more that package weighs inside your bundle.

For Vite:

npx vite-bundle-visualizer

For webpack there's the webpack-bundle-analyzer plugin. A universal option that works off already-built files, if the code maps sit next to them:

npx source-map-explorer dist/assets/*.js

A picture opens, and the unpleasant part is usually visible immediately: half the area is one package you never thought about. An entire date library. An icon set you use four glyphs from. A charting library for a single donut.

Step 3. Deal with the biggest rectangle

Just one — the biggest. Three fixes, in order of effort:

  • Import it differently. A package often ships whole because of its format or because you imported "the entire object". Check whether an ESM build exists and use named imports — the mechanics are unpacked in the piece on what tree shaking is.
  • Swap it for something light. Most heavy libraries have a modern compact equivalent. Date formatting, network requests, juggling CSS classes — nearly all of it is either in the browser now or available at a fraction of the weight.
  • Delete it. The most underrated option. A package you use one fifteen-line function from is more honestly rewritten in your own code.

Repeat steps 2 and 3 once more. Two passes usually cut the bulk of it.

Step 4. Check what runs, not just what weighs

In Chrome, open DevTools, hit Ctrl+Shift+P and type "Coverage". A coverage panel appears: reload the page and see what share of the downloaded code actually ran.

A 70% red bar on a file means someone downloaded and parsed code this page never needed. That's your shortlist for the next step.

Step 5. Split the rare stuff into its own chunks

Anything not needed on first load moves to a dynamic import:

const { default: Chart } = await import("chart.js");

The bundler cuts it into a separate file that only travels the network when it's called. Cut by route and by heavy widget — map, editor, PDF export. Where splitting pays off and where it backfires is covered in the piece on what code splitting is.

Don't get carried away: every chunk is another network trip, and a chain of three nested imports can end up slower than one file.

Step 6. Turn on compression and re-measure

The last step isn't about your code, it's about the server. Check the files leave compressed: open the Network tab, click a JS file and look for a content-encoding response header set to br or gzip. No header means you're shipping text at full size — the cheapest win of the lot. How those two differ from minification is in the breakdown of minification versus compression.

Now repeat step 1 and compare with what you wrote down.

What you'll get

Rough magnitudes on a typical project where nobody has looked at size before:

  • Step 3 (one heavy dependency) — usually the biggest single win, tens of percent of the bundle.
  • Step 5 (routes in their own chunks) — the first load gets noticeably lighter, the total stays the same.
  • Step 6 (compression on the server) — text shrinks several times over, configured once and forever.

And the thing that changes outside the numbers: the page starts answering taps immediately instead of after a pause while the browser chews through a script.

At what size is this worth doing at all?

While your production JavaScript fits into 100–150 KB compressed, it isn't. Past that, every extra hundred kilobytes is noticeable on an average phone.

Why do I get dozens of files after a build instead of one?

That's expected: the bundler splits code into a shared piece plus per-page pieces on its own. Lots of small files aren't a problem, as long as there aren't hundreds and they aren't chained.

What if the heavy package has no replacement?

Keep it, just not in the first load: wrap it in a dynamic import and show a placeholder meanwhile. People only pay for it if they actually open that screen.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →