If you’re a web developer, I’m sure that you’ve heard about *tree-shaking*. It’s often understood as the removal of unused code from JavaScript bundles. However, do you know that not all code that looks unused is tree-shakeable?

In this blog post, we’ll learn more about tree-shaking and tree-shakable design. You’ll know to write JavaScript code in a tree-shakeable way and produce smaller bundles. If you’re building a JavaScript library, is a must.

> This is a part of the series of posts on [best practices](https://cube.dev/blog/category/best-practices) where I’m sharing bits of my experience contributing to open source. It’s both my hobby and job at [Cube](http://cube.dev) where we create and maintain open source tools for building data applications.

## What is tree-shaking?

Wait! If tree-shaking is the removal of unused code from bundles, then how is it different from “dead code elimination” that has been a feature of JavaScript minifiers for quite a while? It’s a fair question, and the answer is that tree-shaking is a later term that is only relevant if JavaScript bundlers and ES6 imports/exports are used.

Bundlers analyze ES6 imports/exports at build time to find unused code. Since ES6 imports/exports are a part of JavaScript syntax, it’s quite easy to perform a static analysis of used and unused exports.

On the other hand, CommonJS exports are resolved at run time and can be dynamic. That’s why static analysis of used and unused exports is impossible for CommonJS modules.

**Let’s compare how Webpack bundles CommonJS and ES6 modules.** In this example, we export two functions (`sum` and `div`) from a CommonJS module but only one of them (`sum`) is imported and used. (Note that here the code in `bundle.js` is shown *before minification*.)

```javascript
// CommonJS
// module.js

exports.sum = function sum(a, b) {
  return a + b;
};

exports.div = function div(a, b) {
  return a / b;
};

// index.js

const { sum } = require('./module');

console.log(sum);

// bundle.js

(() => {
  var __webpack_modules__ = ({
    739:
      ((__unused_webpack_module, exports) => {
        exports.sum = function sum(a, b) {
          return a + b;
        };

        exports.div = function div(a, b) {
          return a / b;
        };
      })
  });

  function __webpack_require__(moduleId) {
    /* ... */
  }

  (() => {
    const { sum } = __webpack_require__(739);

    console.log(sum);
  })();
})();
```

You can see that Webpack added the `__webpack_require__` function to the bundle to support CommonJS module loading. Also, the `div` function is present in the bundle and won’t be removed after minification because it’s assigned to an object property (`exports.div`) and will be considered “used”. Compare to an ES6 module:

```javascript
// ESM
// module.js

export function sum(a, b) {
  return a + b;
}

export function div(a, b) {
  return a / b;
}

// index.js

import { sum } from './module.js';

console.log(sum);

// bundle.js

(() => {
  "use strict";

  function sum(a, b) {
    return a + b;
  }

  function div(a, b) {
    return a / b;
  }

  console.log(sum)
})();
```

You can see that the `div` function was copied “as is” and is not used in any way. When you run Webpack in production mode, it will remove this function. (Internally, Webpack relies on [Terser](https://terser.org/) for minification; [Rollup](https://rollupjs.org/) performs tree-shaking and dead code elimination on its own.) 

## What is tree-shakable code?

In the example above, two functions were exported from the module and only the “used” one made it to the bundle. What if not only functions are exported? (Note that here the code in `bundle.js` is shown *after minification*.)

```jsx
// module.js

export const foo = 'bar'.toUpperCase();

export const PI_2 = Math.PI * 2;

export function sum(a, b) {
  return a + b;
}

// index.js

import { sum } from './module.js'

console.log(sum);

// bundle.js

(() => {
  "use strict";
  "bar".toUpperCase(), Math.PI;
  console.log((function(a, b) {
    return a + b;
  }));
})();
```

You might be surprised that all exported entities are present in the bundle, although only the `sum` function was imported. Let’s explore why.

### Pure code

Removing unused functions is quite straightforward. If a function is never called, its declaration should be considered “dead code” and removed from the bundle. It works because function declarations have no *side effects*: they don’t update global variables, don’t work with DOM, etc. (Please don’t confuse function declarations with function calls; the latter may have side effects.)

Consider the first exported entity: `'bar'.toUpperCase()`. This is a function call and it may have side effects. Well, we know that `toUpperCase` is a *pure function*, meaning calling it has no side effects. However, minifiers know nothing about the standard library. That’s why the function call wasn't removed from the bundle so the code doesn’t break.

Now consider the second exported entity: `Math.PI * 2`. This is an arithmetic operation (a constant is multiplied by two) and should not have any side effects. Now take a closer look: what does `Math.PI` do? It denotes access to a property of an object and it may have side effects. Access to a variable is always pure, but access to a property may invoke a getter method that can do anything. Minifiers don’t know how pure that code is so they leave it intact. (Obviously, this logic applied to setters as well.)

### How to make pure code tree-shakable?

If you know that some code is pure, there’s a way to tell minifiers about that. By convention, placing the `/* #__PURE__ */` comment before a function call or a constructor call (`new`) marks them as pure. If you need to mark access to a property as pure, you can wrap it with a pure function:

```jsx
// module.js

export const foo = /* #__PURE__ */ 'bar'.toUpperCase();

function getPi2() {
  return Math.PI * 2;
}

export const PI_2 = /* #__PURE__ */ getPi2();

export function sum(a, b) {
  return a + b;
}

// index.js

import { sum } from './module.js'

console.log(sum);

// bundle.js

(() => {
  "use strict";
  console.log((function(a, b) {
    return a + b;
  }));
})();
```

Now it looks better, right?

Here are a few real-world examples of code purification from my contributions to open source:

- In [Chart.js](https://www.chartjs.org), tree-shaking [didn’t work as expected](https://github.com/chartjs/Chart.js/issues/10163) because of assignments to class properties ([replaced with static properties](https://github.com/chartjs/Chart.js/pull/10504/files#diff-20242c6d6e67c730511b603d00054d6c95d7698f180cc1eaeeff4dd3278b9c98)).
- In [react-chartjs-2](https://react-chartjs-2.js.org), some exported entities are constructed by calling a factory method ([marked as pure](https://github.com/reactchartjs/react-chartjs-2/blob/59b64feb7d9a24b3557e253f9089225031ce2b72/src/typedCharts.tsx#L33-L59)).

You can experiment with dead code detection yourself in [Terser REPL](https://try.terser.org/).

### `sideEffects: false`

If you’re building a library, you should know about the `sideEffects` property in the `package.json` file. It's similar to `/* #__PURE__ */` but on a module level instead of a statement level. By setting it to `false`, you can mark the entire code of your library as pure:

```json
{
  "sideEffects": false
}
```

You can also set it to an array of files that contain side effects:

```json
{
  "sideEffects": ["./dist/polyfill.js"]
}
```

You can learn more about the `sideEffects` property in the [Webpack documentation](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free). Please pay attention to this behavior: a package, marked as pure with `sideEffects: false`, will be skipped entirely if imported as a whole.

```javascript
// module.js

export const foo = 'bar'.toUpperCase();

export const PI_2 = Math.PI * 2;

export function sum(a, b) {
  return a + b;
}

// index.js

import './module.js'

console.log('noop');

// bundle.js

(() => {
  "use strict";
  console.log('noop');
})();
```

However, if individual entities are imported, everything works as described in the previous section and you still need to use `/* #__PURE__ */`:

```javascript
// module.js

export const foo = 'bar'.toUpperCase();

export const PI_2 = Math.PI * 2;

export function sum(a, b) {
  return a + b;
}

// index.js

import { sum } from './module.js'

console.log(sum);

// bundle.js

(() => {
  "use strict";
  "bar".toUpperCase(), Math.PI;
  console.log((function(a, b) {
    return a + b;
  }));
})();
```

Things to consider when using `sideEffects: false`:

- If your library code is already covered with `/* #__PURE__ */`, using `sideEffects: false` will have no effect.
- If your library provides global style sheets (not [CSS modules](https://webpack.js.org/loaders/css-loader/#modules)), they should also be added to the array of files that contain side effects:

```json
{
  "sideEffects": ["./dist/index.css"]
}
```

It’s required because such style sheets are usually imported directly:

```javascript
import 'mylib/dist/index.css'
```

- Beware when developing a library: bundlers will look for `sideEffects: false` not only in the dependencies of your library but in its `package.json` as well.

## Tree-shakable design

Now we know how tree-shaking works in principle. However, we should also design a library in a tree-shakeable way. For instance, if the entire library is packed in a single class, tree-shaking wouldn’t be able to remove any code.

Here are the rules of tree-shakable design:

1. All entities, including class methods, that might not be used should be exported separately (so they can potentially be removed from the bundle).
2. Classes and objects should be exported cautiously (because their contents can’t be removed from the bundle).
3. All code should be free of side effects by default. Minimal, if any, instances of non-pure code should be permitted. 

Consider the following examples.

### Example A

Imagine we’re writing an internationalization library:

```javascript
// non-tree-shakable

import I18n from 'my-i18n-lib';

const i18n = new I18n(config);

console.log(i18n.__('foo'));
// console.log(i18n.__n('bar', 5));

// tree-shakable

import { I18n, translate, translatePlural } from 'my-i18n-lib';

const i18n = new I18n(config);
const __ = i18n.bind(translate);

console.log(__('foo'));
```

🙅 In the non-tree-shakable variant, a single giant class is exported. The bundle will include all class methods, including unused ones.

🙆 In the tree-shakable variant, potentially unused class methods are exported separately as functions. The bundle will include only used functions.

### Example B

Imagine we’re writing a data visualization library:

```javascript
// non-tree-shakable

import { BarChart } from 'my-charting-lib';

new BarChart('#chart', data, {
  axisX: {
    type: 'auto'
  },
  axisY: {
    type: 'fixed' // 'step'
  }
});

// tree-shakable

import {
  BarChart,
  AutoScaleAxis,
  FixedScaleAxis,
  StepAxis
} from 'my-charting-lib';

new BarChart('#chart', data, {
  axisX: {
    type: AutoScaleAxis
  },
  axisY: {
    type: FixedScaleAxis
  }
});
```

🙅 In the non-tree-shakable variant, all axis types should be imported inside `BarChart` so it can use some of them according to the options provided. The bundle will include all classes for all axis types.

🙆 In the tree-shakable variant, only necessary axis types are imported and provided to `BarChart`. The bundle will include classes only for used axis types.

(Full disclosure: this is a real-world design decision from [Chartist](https://github.com/chartist-js/chartist), an open-source data visualization library I maintain and contribute to.)

### Example C

Imagine we’re writing a more complex data visualization library like [Chart.js](https://github.com/chartjs/Chart.js). In that case, you may choose to implement [dependency injection](https://medium.com/geekculture/dependency-injection-in-javascript-2d2e4ad9df49):

```javascript
import {
  Chart,
  CategoryScale,
  LinearScale,
  PointElement,
  LineElement,
  Title,
  Legend
} from 'chart.js';

Chart.register(
  CategoryScale,
  LinearScale,
  PointElement,
  LineElement,
  Title,
  Legend
);

new Chart(ctx, {
  type: 'line',
  data: data,
  options: {
    plugins: {
      legend: {
        position: 'top',
      },
      title: {
        display: true,
        text: 'Chart.js Line Chart',
      },
    }
  }
});
```

🙆 In this tree-shakable implementation, dependency injection via `Chart.register` is used. Library code is very well split into individual parts that are exported separately. The bundle will include classes only for used entities.

## Keeping code tree-shakable

A one-time effort to write or rewrite a JavaScript library in a tree-shakable way is not enough. One day, due to lousy code or code review, tree-shaking might brake.

However, you can use the [Size Limit](https://github.com/ai/size-limit) library to control the size of a bundle or individual exports. Here’s an example configuration:  

```javascript
// .size-limit.json

[
  {
    "path": "dist/chart.esm.js",
    "limit": "19 KB",
    "import": "{ BarController, BubbleController, DoughnutController, LineController, PolarAreaController, PieController, RadarController, ScatterController }"
  },
  {
    "path": "dist/chart.esm.js",
    "limit": "14 KB",
    "import": "{ ArcElement, LineElement, PointElement, BarElement }"
  },
  {
    "path": "dist/chart.esm.js",
    "limit": "27 KB",
    "import": "{ Decimation, Filler, Legend, SubTitle, Title, Tooltip }"
  },
  {
    "path": "dist/chart.esm.js",
    "limit": "22 KB",
    "import": "{ CategoryScale, LinearScale, LogarithmicScale, RadialLinearScale, TimeScale, TimeSeriesScale }"
  }
]
```

Size Limit integrates with CI such as GitHub Actions and will alert you if any pull request drastically increases the bundle size, possibly due to broken tree-shaking.

## What’s next?

Please use tree-shaking in your code at all times. If you’d like to learn how tree-shaking works by example, check out [this sandbox](https://codesandbox.io/s/webpack-tree-shaking-test-glb8ov?file=/src/module.js) I’ve built.

If you have an existing application or library:

- make sure it complies with the three rules of tree-shakable design;
- make sure pure functions are marked as such with `/* #__PURE__ */`;
- make sure [Size Limit](https://github.com/ai/size-limit) is used to notify if tree-shaking brakes.

Good luck!

Dan Onoshko

Best Practices

How to build tree-shakeable JavaScript libraries

If you’re a web developer, I’m sure that you use bundlers (e.g., [Webpack](https://webpack.js.org), [Rollup](https://rollupjs.org/guide/en/), or [Parcel](https://parceljs.org)) which transpile the JavaScript code of your application with [Babel](https://babeljs.io) under the hood. No doubt that you also use various dependencies to cut off the development time.

However, I rarely see developers transpiling the code of their dependencies because everything seems to work fine without it, right? Wrong! Here’s why...

> This is a part of the series of posts on [best practices](https://cube.dev/blog/category/best-practices) where I’m sharing bits of my experience contributing to open source. It’s both my hobby and job at [Cube](http://cube.dev) where we create and maintain open source tools for building data applications.

## Adoption of ESM

Before browsers and Node.js got native support for ES modules, an npm package could contain several variants of source code:

- [CommonJS](https://en.wikipedia.org/wiki/CommonJS) variant that doesn’t use [modern features](http://es6-features.org/#ExpressionBodies) of JavaScript such as arrow functions. It’s compatible with most versions of Node.js and browsers. The source code location is specified in the `main` field of `package.json`.
- module variant that has ES6 imports/exports but still doesn’t use modern features of JavaScript. Modules allow for [tree-shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking), i.e., excluding unused code from a bundle. The source code location is specified in the `module` field of `package.json` (see [this discussion](https://stackoverflow.com/questions/42708484/what-is-the-module-package-json-field-for) for details).

Obviously, not every npm package follows this convention. It’s a choice that every author of a library makes on their own. However, it’s quite common for browser-side and universal libraries to be distributed in two variants. 

[Web browsers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) have natively supported ES modules for more than three years already, and [Node.js](https://nodejs.org/api/esm.html) supports them since version 12.20 (released in November 2020). That’s why authors of libraries now include one more variant of source code for execution environments that natively support ES modules, and many packages have completely removed the support for CommonJS.

## Perks and features of ESM

It’s important to understand that native ES modules are very much different than modules that have ES6 imports/exports. Here are a few reasons:

- The way we are used to using imports/exports will not work natively. Such code is intended for further processing by a bundler or a transpiler.
- Native ES modules don’t support `index` file name and extension resolution, so you have to specify them explicitly in the import path:

    ```javascript
    // Won't work:
    import _ from './utils'

    // Works:
    import _ from './utils/index.js'
    ```

- If an npm package has ES modules, you have to add `"type": "module"` to `package.json` and specify the source code location in the `exports` field (see [docs](https://nodejs.org/api/packages.html#exports) for details).

You can check [this blog post](https://2ality.com/2019/10/hybrid-npm-packages.html) by Axel Rauschmayer to learn more about ES modules.

## Support for JavaScript features

Look! Since we know which versions of web browsers and Node.js support ES modules, we also know for sure which features of JavaScript we can use in the source code.

For instance, all web browsers that support ES modules natively also support [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions), so we don’t need to avoid using them or use Babel to transpile them to regular functions. Authors of libraries know that and ship the source code that leverages all modern features of JavaScript.

## Transpilation of dependencies’ code

But wait! What can you do to make sure that your web application works in legacy browsers? Also, what to do if any of your application’s dependencies use modern features of JavaScript that aren’t supported by popular browsers? 

In both cases, you need to transpile the code of the dependencies.

### Manual transpilation

Let’s assume that we’re using webpack and [babel-loader](https://webpack.js.org/loaders/babel-loader/#usage). Often, the config would look like this: 

```javascript
module: {
  rules: [
    {
      test: /\.jsx?$/,
      exclude: /node_modules/,
      use: {
        loader: 'babel-loader',
        options: {
          presets: [
            ['@babel/preset-env', { targets: 'defaults' }]
          ]
        }
      }
    }
  ]
}
```

It’s suggested in the documentation and usage examples for Babel and `babel-loader` to exclude `node_modules` from transpilation (`exclude: /node_modules/`) to optimize the performance.

By removing the `exclude` rule, we’ll **enable the transpilation of dependencies’ code** in exchange for the increased bundling time. By providing a custom function as the `exclude` rule, we also can transpile just a subset of all dependencies:

```javascript
exclude: _ => /node_modules/.test(_) && !/node_modules\/(nanostores|p-limit)/.test(_)
```

We can also select files by their filename extensions:

```javascript
exclude: _ => /node_modules/.test(_) && !/(\.babel\.js|\.mjs|\.es)$/.test(_)
```

### Manual transpilation — the benchmark

Let’s check how `babel-loader` configuration affects the bundle size and bundling time. Consider an application with three very different dependencies:

- [svelte](https://www.npmjs.com/package/svelte) (uses modern features of JavaScript such as arrow functions)
- [p-limit](http://npmjs.com/package/p-limit) (uses bleeding-edge features of JavaScript such as private class fields)
- [axios](http://npmjs.com/package/axios) (regular ES5 code)

| Config | Transpilation | Compatibility | Bundle size | Bundling time |
| --- | --- | --- | --- | --- |
| Basic | — | No way to predict which web browsers will work with this bundle | 21 KB | 1.8 s |
| `target: defaults and supports es6-module` | To ES6 code. Private class fields will be downgraded, arrow functions and classes will remain as is | Modern browsers  | 22 KB | 2.6 s |
| `target: defaults` with polyfills | To ES5 code | All browsers | 123 KB | 6.1 s |

You can see that the total bundling time for modern browsers and all browsers with `babel-loader` is 8.7 s. Please also note that the basic, non-transpiled bundle won’t work with legacy browsers because of `p-limit`.

(By the way, I also have a [blog post](https://dev.to/dangreen/speed-up-with-browserslist-30lh) that explains in detail how to build several bundles for different browsers.)

Okay, but what if you don’t want to tinker with configs and specify files and packages to be transpiled manually? Actually, there’s a readily available tool for that!

### Transpilation with optimize-plugin

Meet [optimize-plugin](https://github.com/developit/optimize-plugin) for webpack by Jason Miller from Google ([@_developit](https://twitter.com/_developit)). It will take care of everything and even more:

- It will transpile your application’s source code and the code of all dependencies.
- If needed, it will generate two bundles (for modern and legacy browsers) using the [module/nomodule pattern](https://jasonformat.com/modern-script-loading/).
- On top of that, it can also upgrade ES5 code to ES6 using [babel-preset-modernize](https://github.com/developit/babel-preset-modernize)!

Let’s see what `optimize-plugin` will do to our example application with three dependencies:

| Config | Transpilation | Compatibility | Bundle size | Bundling time |
| --- | --- | --- | --- | --- |
| Basic | To ES6 code. Also, to ES5 code with polyfills | All browsers | 20 KB for modern browsers. 92 KB for legacy browsers (including 67 KB of polyfills) | 7.6 s |

The total bundling time with `optimize-plugin` is 7.6 s. As you can see, `optimize-plugin` is not only faster than `babel-loader`, but it also produces a smaller bundle. You can check my results using the code from my [optimize-plugin-demo](https://github.com/dangreen/optimize-plugin-demo) repository.

### Why optimize-plugin wins

The performance boost is possible because the code is analyzed and bundled only once. After that, `optimize-plugin` transpiles it for modern and legacy browsers.

Smaller bundle size is possible thanks to [babel-preset-modernize](https://github.com/developit/babel-preset-modernize). Chances are that you use ES6+ features in your application’s code but you never can predict which features are used in the code of the dependencies. Since `optimize-plugin` works with the bundle that already has the code of all dependencies, it can transpile it as a whole.

Here’s how `babel-preset-modernize` works. Consider this code snippet:

```javascript
const items = [{
  id: 0,
  price: 400
}, {
  id: 1,
  price: 300
}, {
  id: 2,
  price: 550
}];
const sum = items.reduce(function (sum, item) {
  const price = item.price;
  return sum + price;
}, 0);

console.log(sum);
```

After transpilation to ES6, we’ll get this code:

```javascript
const items = [{
  id: 0,
  price: 400
}, {
  id: 1,
  price: 300
}, {
  id: 2,
  price: 550
}];
const sum = items.reduce((sum, {
  price
}) => sum + price, 0);

console.log(sum);
```

Here’s what has changed:

- A regular anonymous function was upgraded to an arrow function.
- `item.price` field access was replaced with the function argument destructuring.

Code size shrinked from 221 to 180 bytes. Note that we applied only two transformations here but `babel-preset-modernize` can do a lot more.

## What’s next?

`optimize-plugin` works really great but it still has some room for improvement. Recently, I’ve [contributed](https://github.com/developit/optimize-plugin/releases/tag/1.1.0) a few pull requests, including the support for webpack 5.

If `optimize-plugin` looks promising to you, I encourage you to [give it a try](https://github.com/developit/optimize-plugin#install) in your projects and maybe contribute some improvements as well.

Anyway, starting today, please always transpile the code of the dependencies, whether with `optimize-plugin` or not, to make sure that you have full control over your application’s compatibility with modern and legacy browsers. Good luck!

Best Practices

How to build tree-shakeable JavaScript libraries

Why and how to transpile dependencies of your JavaScript application