How does 'tree-shaking' in a JavaScript bundler like webpack or Rollup actually decide what code to eliminate from a production bundle, and what has to be true about a dependency for tree-shaking to work on it?

## What tree-shaking is **Tree-shaking** is dead-code elimination applied specifically to JavaScript module graphs: a build-time step, run by a bundler like webpack, Rollup, or esbuild, that determines which exported values from your dependencies (and your own code) are ever actually referenced by anything reachable from the app's entry point, and strips everything else out of the final bundle before it's minified and shipped to the browser. The motivation is straightforward — a library might export fifty utility functions, but if your app only calls three of them, shipping the other forty-seven down the wire to every user on every page load is pure waste, directly hurting page-load performance, which is why this matters enough to be a standard step in virtually every modern frontend build pipeline. ## Why it needs ES module syntax The mechanism depends critically on **ES module (ESM)** syntax — `import { x } from 'module'` and `export const x = ...` — because these are, by spec, **static**: the set of imported and exported bindings is fully determined at parse time, before any code runs, and can't be changed dynamically (you can't conditionally import a different name inside an `if` block the way you could with `require()` in CommonJS, where module loading is an ordinary runtime function call that could in principle be passed any string). That static, analyzable structure lets a bundler build an exact graph: 1. entry point imports A and B from module M; 2. module M's implementation of A imports C from module N; 3. therefore N's export C is 'reachable' and everything else N exports is not. **CommonJS** (`const _ = require('lodash')`, `module.exports = {...}`), by contrast, is opaque to static analysis in the general case — the bundler can't prove which properties of the exported object get used, or whether `require` calls might be dynamic — so packages that ship only a CommonJS build generally can't be tree-shaken at all; the whole module gets included if any part of it is imported. ## The side-effects requirement Beyond ESM syntax, the second requirement is proving the elimination is safe, which comes down to **side effects**. A module is 'side-effect-free' if importing it and not using any of its exports has zero observable effect on the program — no top-level code that mutates a global, registers a polyfill, attaches a CSS stylesheet, or logs something. - If a bundler can't prove that, it has to conservatively keep the module's top-level code even when none of its named exports are used, because deleting it could silently change behavior (imagine a module whose only job is `Array.prototype.includes = polyfillFn` at import time — nothing 'uses' an export, but removing the import breaks the app on older browsers). - Since proving this automatically for arbitrary code is hard, the ecosystem convention is a `package.json` field, `'sideEffects': false` (or an array of specific files that do have side effects, e.g. CSS entry points), that lets the library author explicitly promise the bundler 'everything else here is safe to drop if unused.' - Without that flag, most bundlers default to the conservative, safe assumption and keep more code than strictly necessary. ## Where real libraries go wrong This is where real libraries commonly go wrong in practice, and **lodash** is the textbook example: `import _ from 'lodash'` pulls in the entire default-exported object, and because the library historically shipped in a form a bundler generally can't fully attribute per-method, the whole library — tens of kilobytes — ends up in the bundle even if you only called `_.debounce`. The two standard fixes are: | Fix | How it works | |---|---| | Importing the specific submodule directly (`import debounce from 'lodash/debounce'`) | Sidesteps the analysis problem entirely by only ever importing exactly the file you need | | Using an ESM-native distribution built for this purpose (`lodash-es`) | Ships proper per-function ES modules that a bundler can shake correctly when you do `import { debounce } from 'lodash-es'` | The same class of problem recurs across the ecosystem with any large utility or component library, which is why many such libraries now ship explicit per-module ESM entry points and `'sideEffects': false` metadata specifically to make tree-shaking work by default rather than by developer effort. ## The trade-off worth naming The trade-off worth naming explicitly is that none of this is free at the tooling or authoring level: - Shipping a properly tree-shakeable library requires maintaining an ESM build target (often alongside a CommonJS build for Node consumers who don't yet support ESM), auditing every module for accidental side effects, and testing that consumer bundlers actually shake as expected — a genuinely side-effect-free-looking module that turns out to run polyfill code at import time will silently break someone's production app the moment they upgrade and their bundler starts eliminating it. - On the consumer side, developers have to actually import named/specific bindings rather than default/barrel imports to get the benefit, which is easy to get wrong without linting rules enforcing it.