Skip to content

Topics

Jump to a topic.

Search questions

Find a question by title, tag, or summary.

How does tree shaking work, and what stops it?

Questions in this chapter (9)
  • Draft
  • medium
  • Askedvery often
  • Verified October 2026

Answer

Tree shaking is dead-code elimination done by bundlers and minifiers (esbuild, Rollup, webpack with Terser), not by the language. ECMAScript contributes syntax a tool can analyse without running it: import and export declarations only appear at the top level of a module, and their specifiers are string literals. So the tool can build the import graph statically, mark which exports the entry point actually reaches, and leave out the rest.

Removal is conservative: top-level code that might have a side effect stays. Calls, property reads (a getter could run) and global writes are kept even when their result is unused. Two hints relax that:

  • /*#__PURE__*/ (or /* @__PURE__ */) before a call or new: "this call can be removed if its result is unused." It promises nothing about the function being pure in the functional sense, and it covers only the call, not side effects in its arguments.
  • "sideEffects" in a package's package.json: a webpack convention, also honoured by esbuild, saying which files have side effects. With false, a module whose exports are all unused can be skipped entirely, including its top-level code. Rollup's core doesn't read this field; @rollup/plugin-node-resolve passes it on.

What defeats tree shaking:

  • CommonJS. require is an ordinary call that can take a computed path anywhere, and module.exports is a mutable object read and written by computed keys. esbuild doesn't shake CommonJS at all; webpack 5 recognises a few static patterns (exports.x = …, require('a').x) and bails out on anything else.
  • Compiling ESM to CommonJS too early, e.g. a Babel config that transforms modules before bundling.
  • Exporting one big object (export default { a, b, c }): the object is used, so all of it stays.
  • Top-level side effects in libraries, such as patching prototypes on import.

Example

// math.js
export const add = (a, b) => a + b;
export const multiply = (a, b) => a * b;
const makeTable = () => Array.from({ length: 4 }, (_, i) => i * i);
export const squares = makeTable(); // a call: kept, it might have side effects
export const cubes = /*#__PURE__*/ makeTable(); // "drop me if unused"

// main.js
import { add } from './math.js';
console.log(add(2, 3));

// $ npx esbuild main.js --bundle --format=esm   (esbuild 0.28.2) writes:
// // math.js
// var add = (a, b) => a + b;
// var makeTable = () => Array.from({ length: 4 }, (_, i) => i * i);
// var squares = makeTable();
//
// // main.js
// console.log(add(2, 3));

Pitfalls

  • Setting "sideEffects": false on a package that imports CSS or polyfills for their effect. Those files are then dropped in production; list them instead ("sideEffects": ["*.css", "./src/polyfills.js"]).
  • Assuming an unused export is gone in every build. webpack enables usedExports by default only in production mode, and esbuild shakes only when bundling or emitting iife.
  • Reading /*#__PURE__*/ as "this function is pure". It means only "this call may be deleted if its value is unused"; it doesn't make repeated calls cacheable.
  • Blaming the tool when a CommonJS dependency ends up whole in the bundle. Prefer packages that ship ES modules (via exports or module).

Follow-ups

How do webpack's usedExports and sideEffects differ?
usedExports marks unused exports so they aren't generated, and the minimizer (Terser) then removes the dead declarations if it can prove them side-effect-free. sideEffects skips whole modules and their dependency subtrees when none of their exports are used. webpack's guide calls the sideEffects flag the more effective of the two.
How do you mark a whole function as removable rather than one call?
Put /*#__NO_SIDE_EFFECTS__*/ before the function declaration. Rollup then treats every unused call as removable, across modules. esbuild 0.28.2 also reads it, but in a test it removed only calls in the declaring file, not calls to an imported function.
Does dynamic import() prevent tree shaking?
It limits it. import('./x.js') yields the whole namespace object, and a tool can't always see which properties are read from it. With --splitting, esbuild 0.28.2 put every export of the example's math.js into the lazy chunk, unused ones included. Static import { x } gives tools the most information.

Exercises

Predict what esbuild keeps

node_modules/fake-ui/package.json has "sideEffects": false. Each file logs on load.

// node_modules/fake-ui/index.js
export { Button } from './button.js';
export { Chart } from './chart.js';
// node_modules/fake-ui/button.js
console.log('button loaded'); export const Button = 'Button';
// node_modules/fake-ui/chart.js
console.log('chart loaded'); export const Chart = 'Chart';
// app.js, bundled with: npx esbuild app.js --bundle --format=esm
import { Button } from 'fake-ui';
console.log(Button);

Predict what webpack keeps

The same math.js and main.js as the example, built with npx webpack --mode=production --entry ./main.js (webpack 5.112.1).

// main.js
import { add } from './math.js';
console.log(add(2, 3));

Comments

Comments are GitHub Discussions: you sign in with GitHub to post or react.