Basics

What is tree shaking — and why lodash still ships to your bundle whole

Illustration: dead branches falling off a tree, only the living wood left

You take one function from a library — say debounce. You write an honest named import. Then you open the finished build and find the whole library in there, all three hundred functions.

The mechanism that was supposed to clean that up is called tree shaking. And it has a condition almost nobody writes about: it doesn't work with every package. With some of the most popular ones it often doesn't work at all.

What it is, in one line

Tree shaking is "shaking off the dead branches": the bundler walks your code from the entry point and drops everything the imports never reached. The term came from the Rollup bundler; every bundler does it now.

The idea is simple. You imported two functions out of three hundred — two should land in the bundle. The catch is that the bundler has to prove what the imports reached, without running the code. And that isn't always provable.

Why it all comes down to the module format

There are two ways to pull in someone else's code.

The modern one, ESM, is import and export. The key property: the list of what a module gives and takes is written in the text of the file and cannot change at runtime. The bundler reads the file and knows the dependency graph exactly.

The old one, CommonJS, is require(). And require is an ordinary function call. It can hide inside an if, build the module name from a variable, sit in a loop. The bundler can't prove what's actually used — so it doesn't gamble. It keeps everything.

Which is where the lodash story comes from. The main lodash package is built as CommonJS: its package.json has neither "type": "module" nor a module field. You write a named import, and there's nothing to shake — the format won't allow it. Unpacked, the package is about 1.4 MB across more than a thousand files.

Right next to it on npm sits lodash-es — the same library, same version, but in ESM. Unpacked it's about 635 KB, and its package.json says "sideEffects": false outright. From that one, the bundler extracts exactly debounce.

Side effects — the second reason it misses

Even with honest ESM, a bundler sometimes won't dare drop a module. The reason is side effects.

A side effect is when a file does something on import instead of just handing back functions. A polyfill that patches a global object. A stylesheet. Registering something in a global registry. Drop a module like that as "unused" and you break the app.

The bundler can't know that about your code, so it plays safe. You tell it with a line in package.json:

{ "sideEffects": false }

That's a promise: "in all my files, importing does nothing beyond exporting". If effects do exist, list the files instead of false:

{ "sideEffects": ["./src/polyfill.js", "*.css"] }

CSS in that list is the most commonly forgotten line. Styles are imported for the effect alone, they export nothing, and without the note they silently fall out of the production build. The classic "looks great locally, ships unstyled" bug.

Three checks before you install a package

This is the practical payoff. Open the package page on npm and read its package.json:

  1. Is there a "type": "module" or a module field? Neither means the package is CommonJS and won't be shaken. Look for an ESM variant: often it sits next to it with an -es suffix, or is already wired up through the exports field, as in date-fns.
  2. Is there "sideEffects": false? If yes, the author did the work for you and the bundler can skip whole files. That's far more effective than analysing individual statements.
  3. How are you importing? import { debounce } from "lodash-es" can be shaken. Importing the whole package as one object almost never can.

And a fourth one, about you rather than the package: tree shaking only runs in the production build. It's deliberately off in development — otherwise debugging would be misery. Don't panic at the file size in npm run dev and don't compare it to production; how to measure properly is in the guide on how to shrink your JavaScript bundle.

Do I need to enable something in the bundler?

No. Vite, webpack and Rollup shake code on their own when building for production. What they need from you is ESM packages and named imports — configuration has almost nothing to do with it.

Why did my bundle barely shrink after moving to ESM?

Most likely side effects: the package has no "sideEffects": false, so the bundler won't risk dropping whole modules. The other common case is that some plugin or preset along the way turns your ESM back into CommonJS.

Is this the same as minification?

No. Minification shortens what has already been kept. Tree shaking decides what to keep at all. They run in order: shaking first, then minification, and only then compression in transit.

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 →