agadoo

Ag-a-doo-doo-doo, push pineapple, shake the tree

What this does

Tells you whether the JavaScript library you're building is tree-shakeable.

What it doesn't do

Tell you why tree-shaking fails, if it does. Maybe in a future version.

Hold up — tree what now?

With the advent of JavaScript modules (import and export), it's possible to build libraries that are tree-shakeable. This means that a user of your library can import just the bits they need, without burdening their users with all the code you're not using.

For example, the eases-jsnext library contains a grab-bag of Robert Penner's easing equations, presented as a JavaScript module. I can use it like this in my code...

1import * as eases from 'eases-jsnext';
2
3for (let t = 0; t <= 1; t += 0.05) {
4  const eased = eases.cubicInOut(t)
5  const str = repeat('*', eased * 20);
6  console.log(str);
7}
8
9function repeat(str, num) {
10  let result = '';
11  num = Math.round(num);
12  while (num--) result += str;
13  return result;
14}

...and all the easing functions that I haven't used will get removed during bundling, if I'm using a modern bundler such as Rollup, webpack or Parcel. Here's what that bundle would look like with Rollup:

1'use strict';
2
3function cubicInOut(t) {
4  return t < 0.5
5    ? 4.0 * t * t * t
6    : 0.5 * Math.pow(2.0 * t - 2.0, 3.0) + 1.0
7}
8
9for (let t = 0; t <= 1; t += 0.05) {
10  const eased = cubicInOut(t);
11  const str = repeat('*', eased * 20);
12  console.log(str);
13}
14
15function repeat(str, num) {
16  let result = '';
17  num = Math.round(num);
18  while (num--) result += str;
19  return result;
20}

...and here's the result of running it:

*
*
**
***
*****
*******
**********
*************
***************
*****************
******************
*******************
*******************
********************
********************
********************

But I digress. The point is that this works because eases-jsnext is a tree-shakeable library.

Using agadoo

Inside your project folder, run Agadoo like so:

1npx agadoo

You can install it as a development dependency and run it each time you npm publish — if tree-shaking fails, publishing will be aborted:

1npm install -D agadoo

1// package.json
2{
3  "scripts": {
4    "prepublishOnly": "agadoo"
5  }
6}

You can specify the module if necessary:

1agadoo dist/my-library.js

Help! My library isn't tree-shakeable and I'm not sure why

Firstly, make sure you're exposing a JavaScript module using the "module" field of your package.json (aka pkg.module).

If tree-shaking still fails, it's because Rollup thinks that there are side-effects somewhere in your code. Follow these guidelines:

• Avoid transpilers like Babel and Bublé (and if you're using TypeScript, target a modern version of JavaScript)
• Export plain functions
• Don't create instances of things on initial evaluation — instantiate lazily, when the functions you export are called

License

LIL.