Stop 16 · PerformanceTopics · 6/13

Tree Shaking

In short

You import one small function from a big library. Tree shaking is how your bundler drops everything you didn't use, so users don't download the whole library for one helper.

A build-time optimization that removes unused exports from your final bundle, based on static analysis of your `import`/`export` statements.

The jaadu shakes a mango tree so dry leaves fall while ripe mangoes stay on.

Think of it like this

Shaking the mango tree

Shake a mango tree and the dry leaves and loose twigs fall off. What's firmly attached stays. Your bundler shakes your code: exports nobody imports fall away, and only code you actually use goes into the bundle.

Watch it happen

Shaking lodash-es at build time

lodash-es

debounce

throttle

chunk

cloneDeep

map

1/4lodash-es is an ES module with hundreds of named exports.

The big ideas

What you need to know

Needs ES modules

import and export are static, so the bundler can see what's used. Old require() code usually can't be shaken.

Import only what you use

Named imports like import { debounce } give the bundler a clear signal. A default import of a whole utility object usually pulls in everything.

Side effects block it

If a file does something on import, like adding a global, the bundler keeps it. "sideEffects": false in package.json says it's safe to drop.

Production builds only

Dev builds usually keep everything for speed. Check bundle size on a production build.

See it in code

Walk through the code

1// Pulls in all of lodash (CommonJS, can't be shaken)2import _ from "lodash";3const save = _.debounce(saveDraft, 500);4 5// Only debounce ends up in the bundle (ES module build)6import { debounce } from "lodash-es";7const save2 = debounce(saveDraft, 500);8 9// In your own library's package.json, tell bundlers files are safe to drop:10// { "sideEffects": false }11// or list files that DO have side effects:12// { "sideEffects": ["*.css"] }

1/3A default import of CommonJS lodash pulls the whole library into your bundle.

lodash-es is the ES module version of lodash. The import style and the package format both decide whether tree shaking can work.

Save yourself the pain

Common mistakes

Oops

Marking a package "sideEffects": false when it imports global CSS.

Do this instead

List the CSS files in sideEffects, or the bundler may drop your styles.

Oops

Assuming tree shaking makes any import cheap.

Do this instead

It only works with ES modules and clean exports. Check the bundle analyser to be sure.

Your mission

Weigh your imports

~20 min

Quick check

Why can a bundler tree-shake import { x } from "lib" but often not const lib = require("lib")?

Go deeper

1Import only one function from a large utility library and confirm the whole library isn't bundled.
2Learn why tree shaking requires ES modules (`import`/`export`), not CommonJS (`require`).
3Check a library's `package.json` for a `sideEffects` field, which affects tree shaking.