JavaScript Code Splitting and Tree Shaking: How to Cut Bundle Size

Every visitor downloads, parses and runs code for screens they never open. On a slow phone, that work can delay the moment the page first responds to a tap. JavaScript code splitting and tree shaking are the two build-time fixes for this.

Picture a common setup. A shop runs an admin web app with an Orders page that staff open all day and a Reports page with charts that a few managers open on Mondays. The setup is made up, but the byte sizes below come from real builds. The first version imports everything at the top of one file, so the Orders page also ships the reporting code.

In our build that single file was 18,745 bytes, minified. After one change and one build flag, the Orders page needed 199 bytes, and the reporting code loaded only when someone opened Reports. This guide shows that change, then the tree shaking rules that decide what is inside each file.

• Module: one JavaScript file that shares some values with other files and uses values from them.
• ES modules (ESM): the standard module syntax with import and export. Bundlers can read these lines without running the code.
• CommonJS (CJS): the older Node.js style, where a file calls require() and fills module.exports while it runs.
• Bundler: a build tool such as esbuild, webpack, Rollup or Vite that follows your imports and writes a few output files.
• Bundle and chunk: a bundle is an output file the browser loads. A chunk is a piece of it that can load on its own.
• Minifier: a build step that shortens names and removes spaces. It also deletes code that can never run.
• Side effect: anything a file does just by loading, such as setting a global value or adding CSS to the page.
• gzip and brotli: compression formats servers use to send fewer bytes. The browser unpacks them, then parses the full raw size.

JavaScript code splitting cuts your app into several files so each page loads only what it needs first. Tree shaking removes exported code that no import uses. Splitting decides when code arrives; tree shaking decides whether it ships at all.

The webpack docs define tree shaking as dead-code elimination that relies on the static structure of import and export. Static means the bundler can see every import before any code runs. That is why the module format matters so much later in this guide.

Think of packing for a work trip. Tree shaking is leaving clothes you will never wear at home. Code splitting is packing a second bag that a courier brings only if you need it. The sideEffects field is a label saying a bag holds no hidden items like medicine you must take.

Where the picture breaks: a bundler never guesses what you will need. It follows import lines exactly, so a single forgotten import keeps a whole file in the main bag.

The bundler marks every export that some import uses and deletes the rest. Here is a small file of price helpers from the admin app, where only one helper is used.

// src/format.js
export function formatPrice(paise) {
  return "Rs " + (paise / 100).toFixed(2);
}

export function buildInvoiceText(order) {
  return "INVOICE for order " + order.id + "\nTotal: " + formatPrice(order.total);
}

// src/app.js
import { formatPrice } from "./format.js";

console.log(formatPrice(129900));

Build it with esbuild and search the output for the word INVOICE. The command below bundles, minifies and writes an ES module file.

npx esbuild src/app.js --bundle --minify --format=esm --outfile=out/app.js
wc -c out/app.js        # 69 out/app.js
grep -c INVOICE out/app.js   # 0

The whole output is one line of 69 bytes, and buildInvoiceText is gone. When app.js imports both helpers, the same build is 160 bytes and the invoice text is back. Webpack 5.112.2 in production mode gave 66 and 168 bytes.

What just happened? The bundler saw that nothing imported buildInvoiceText, so it never wrote it out. You did not delete anything by hand, and the source file still exports both helpers for other pages.

Esbuild works differently. Its source code turns tree shaking on whenever it bundles, and our build without --minify was 141 bytes, with the invoice helper already gone.

It keeps any top-level code that might have a side effect, because removing it could change what your app does. Top-level code is code outside any function, which runs the moment the file loads.

Say the admin app uses a small chart library, chart-kit, a made-up package we wrote for these tests. The app imports only formatAxis, a helper that turns 250000 into 2.5 lakh (250 thousand). The library's draw.js file builds a colour palette at the top level.

// node_modules/chart-kit/draw.js
const palette = makePalette(12);

function makePalette(n) {
  return Array.from({ length: n }, function (_, i) {
    return "hsl(" + i * 30 + ", 70%, 50%)";
  });
}

export function drawChart(ctx, values) {
  values.forEach(function (v, i) {
    ctx.fillStyle = palette[i % palette.length];
    ctx.fillRect(i * 10, 100 - v, 8, v);
  });
}

Nothing in the app uses drawChart, and every bundler we tried removed it. But all three kept the makePalette call. The esbuild output was 172 bytes and webpack's was 130 bytes, both still building colours nobody reads.

The bundlers cannot prove that calling makePalette, which calls Array.from, is harmless. Deciding whether any function call is safe to skip is hard in JavaScript, so bundlers stay careful.

Two ways to tell the bundler the code is safe

You can mark a single call as pure, meaning it has no side effects, with a special comment before it. Writing /* @__PURE__ */ makePalette(12) removed the palette in esbuild, webpack and Rollup, giving 69 and 59 bytes in the first two. The webpack docs describe the same annotation.

The second way works on whole files, and it is the next section. The webpack docs call it much more effective, because it can skip whole files and everything they import.

It is a promise from the package author that no file in the package does anything just by being imported. With that promise, a bundler can skip any file whose exports you do not use, including its top-level code.

{
  "name": "chart-kit",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "sideEffects": false
}

With this one field added, the same app shrank from 172 to 69 bytes in esbuild and from 130 to 59 bytes in webpack. The palette code was gone because draw.js was skipped completely.

This field belongs to bundlers, not to Node.js. The Node.js packages documentation lists the fields Node reads as name, main, type, exports and imports, and says other fields are ignored by Node.js. Node itself runs every file you import, whatever the field says.

When sideEffects false breaks your app

Some files exist only for their side effects. A CSS import, a polyfill or a setup file that registers chart themes exports nothing, so a wrong false tells the bundler to drop them.

// node_modules/chart-kit/register.js
globalThis.chartKitThemes = ["light", "dark"];

// src/register-app.js
import "chart-kit/register.js";

console.log(globalThis.chartKitThemes);

Without the field, both bundles printed the two themes. With sideEffects false, both printed undefined, because the import was removed. Esbuild 0.28.2 printed a warning starting Ignoring this import because the file was marked as having no side effects.

Webpack 5.112.2 dropped the same import and reported compiled successfully, with no warning, even in development mode. That silence is observed behaviour, not something the webpack docs promise either way, as of 24 October 2026. Pin your version and test the real page.

The fix is the array form, which lists the files that do have side effects. The webpack docs say patterns without a slash, like *.css, match in every folder.

{
  "name": "chart-kit",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "sideEffects": ["./register.js", "*.css"]
}

With that list, both bundles printed the themes again. The same rule applies to your own app's package.json, not only to libraries you publish.

CommonJS builds its exports while the code runs, so a bundler often cannot see which exports exist or which ones you use. Faced with that, esbuild and Rollup keep the whole file.

Here is the chart helper again, this time written in CommonJS. The app still imports only formatAxis, and the package still says sideEffects false.

// node_modules/chart-kit-cjs/index.js
function formatAxis(n) {
  return (n / 100000).toFixed(1) + " lakh";
}

function drawChart(ctx, values) {
  values.forEach(function (v, i) {
    ctx.fillRect(i * 10, 100 - v, 8, v);
  });
}

exports.formatAxis = formatAxis;
exports.drawChart = drawChart;

Pause and predict: will drawChart stay in the bundle? The ES module version of this library gave a 69-byte esbuild bundle without drawChart.

The CommonJS version gave 763 bytes with esbuild, and drawChart was still inside. The extra bytes are drawChart plus a small wrapper esbuild adds to run CommonJS code. Rollup with its CommonJS plugin also kept drawChart. Its output, which we did not minify, was 574 bytes.

Webpack 5.112.2 surprised us. It removed drawChart and produced 271 bytes, because webpack 5 added support for some simple CommonJS patterns. Its release post lists patterns like exports.name = value, and says it stops tracking exports when it finds code it cannot analyse.

We checked that limit. When the library copied its exports in a loop, webpack kept drawChart too, at 633 bytes. So treat CommonJS as unshakeable unless you have measured your own bundler on your own library.

The same lesson with a real library

Lodash is a popular helper library. The lodash package is CommonJS, and lodash-es is its ES module build, with type module and sideEffects false in its package.json. We imported only debounce, a helper that waits until calls stop before running a function.

The CommonJS import shipped the whole library: 18 to 23 times more gzip bytes for one function. Importing the single file is a workaround when a library has no ES module build.

Your own code can fall into the same trap. The webpack docs warn that a compiler may turn your import lines into CommonJS, and they name the popular Babel preset-env default. Check your build output, not only your source.

Writing import() as a function call lets a bundler that supports splitting put that module and its imports in a separate file. The browser fetches it only when the line runs. MDN describes import() as returning a promise for the module's exports, and lists it as widely available in browsers since January 2020.

A promise is a value that arrives later, which is why the code uses await. Here is the admin app's router after the change.

// src/main.js
import { renderOrders } from "./pages/orders.js";

async function route(path, el) {
  if (path === "/reports") {
    const { renderReports } = await import("./pages/reports.js");
    renderReports(el, []);
  } else {
    renderOrders(el);
  }
}

route(location.pathname, document.body);

The old version imported renderReports at the top, so its lodash-es helpers were in the main file. Build both with esbuild's splitting option and compare.

npx esbuild src/main.js --bundle --minify --format=esm --splitting --outdir=out/split
#  out/split/reports-ECIECDVG.js  18.2kb
#  out/split/main.js               199b

What just happened? The Orders page now loads 177 gzip bytes instead of 7,269. The reports code did not shrink; it moved to a file that only Reports users download.

Webpack split the code with no extra settings. Its main file is larger because it carries a small runtime that fetches chunks, and it put lodash-es in its own vendors chunk.

Two ways to write import() and still ship one big file

First, the bundler has to support splitting for your output format. Without the splitting option, esbuild kept the reports code inside main.js, and the file grew to 22,505 bytes. Esbuild's docs say splitting only works with the esm format, and asking for iife failed with that error.

Second, one leftover static import cancels the split. When main.js also imported renderReports at the top, webpack wrote a single 16,741-byte file. Esbuild moved the code into a shared chunk that main.js imports at startup, so it still loaded on Orders.

Wrap the dynamic import in React's lazy function, and show a fallback with Suspense while the chunk loads. Suspense is a React component that shows a placeholder until the code inside it is ready.

// src/App.js (React 19.3.1, plain createElement calls, no JSX)
import { createElement, lazy, Suspense, useState } from "react";
import { createRoot } from "react-dom/client";

const Reports = lazy(function () {
  return import("./Reports.js");
});

function App() {
  const [tab, setTab] = useState("orders");
  if (tab === "reports") {
    return createElement(Suspense, { fallback: "Loading reports..." },
      createElement(Reports, { orders: [] }));
  }
  return createElement("button", { onClick: function () { setTab("reports"); } }, "Reports");
}

createRoot(document.getElementById("root")).render(createElement(App));

Esbuild produced a 17,399-byte Reports chunk that loads on the first click. It also wrote an 8,792-byte shared chunk with React code that both files use. The entry file was 214,215 bytes, or 66,399 bytes gzip.

Esbuild's analyze report showed where those bytes came from. React DOM's client file, loaded from its cjs folder, was 200.1 kB of the 209.2 kB entry file. That is a CommonJS file, so esbuild bundles it whole. Splitting your own pages is the lever you control.

Measure the production build after every change, and make the build fail when a file passes a size you agreed on. A size limit like this is called a performance budget.

Which numbers to look at

Raw bytes are the size on disk after minifying. Gzip and brotli bytes are roughly what travels over the network. Keep both: the download depends on the compressed size, while the browser still parses every raw byte.

• Esbuild: add --analyze to print each output file with the modules inside it and their share, or --metafile to save build data, including input and output sizes, as JSON.
• Webpack: the code splitting guide lists tools such as webpack-bundle-analyzer, which draws the bundle's contents as a zoomable treemap.
• Chrome DevTools: the Coverage panel lists each loaded file with an Unused Bytes column for the page you are on.
• Any setup: compress the files yourself, as we did with Node's zlib module, and compare runs.

A budget that fails the build

Webpack has budgets built in. The performance settings warn by default in production mode for any asset or entry point over 250,000 bytes. Set hints to error and the build fails instead.

// budget.webpack.config.js
module.exports = {
  mode: "production",
  entry: "./src/main-static.js",
  performance: {
    hints: "error",
    maxEntrypointSize: 10000,
    maxAssetSize: 10000,
  },
};

Run npx webpack -c budget.webpack.config.js on the old static version. You should see ERROR in asset size limit, naming main.js at 15.9 KiB against a 9.77 KiB limit, and exit code 1. A KiB is 1,024 bytes, so 10,000 bytes shows as 9.77 KiB.

Our file was 16,270 bytes raw and 5,761 bytes gzip, and webpack compared the raw size. The docs only say the limits are in bytes, so set your numbers against raw, minified output.

1. 1

   Record today's sizes

   Build in production mode and write down raw and gzip bytes for every file the first page loads.

2. 2

   Set the budget a little above today

   Pick a limit just above the current entry size, so any real growth breaks the build.

3. 3

   Fail the build in CI

   Set webpack performance hints to error, or run a small script that compresses each file and exits with code 1 when one is over.

4. 4

   Read the report when it fails

   Run esbuild --analyze or a bundle analyzer, find the new module, then split it, shake it or replace it.

5. 5

   Raise the limit only on purpose

   Change the number in a reviewed commit that says why the page needs more code.

They agree on the basics and disagree on the edges. Every result below ran on esbuild 0.28.2, webpack 5.112.2 and Rollup 4.65.0, as of 24 October 2026. Rollup ran with its node-resolve and CommonJS plugins and without a minifier.

The last row catches many teams. A file that ends with export default followed by an object of helpers bundles every helper with esbuild and Rollup. Named exports were removed by all three.

The webpack cells for CommonJS and default objects describe observed behaviour, not documented promises. Pin your bundler version and re-run your size check after upgrades.

Start from the user's first screen, then show how you keep only its code on the critical path and stop the bundle growing back. Use this frame.

1. 1

   Name the cost

   Every first visit downloads, parses and runs the main bundle, so its size shapes how soon the page responds on slow phones.

2. 2

   Split by route and heavy widget

   Use dynamic import() for pages and large components most users never open, with a loading state and optional prefetch.

3. 3

   Make tree shaking possible

   Use ES modules end to end, prefer libraries with ES module builds, and export small named functions.

4. 4

   Mark side effects honestly

   Set sideEffects in package.json, listing CSS and setup files, so whole unused files are skipped safely.

5. 5

   Measure and guard

   Track raw and gzip sizes per file, inspect with an analyzer, and fail CI when a budget is crossed.

6. 6

   State the trade-off

   More chunks mean more requests and a short wait on first use, so split where the saving is large.