How to Make an npm Package Support Tree Shaking Using the pkg.module Field

Tree Shaking is a technique that removes unused code from a bundle by analyzing static ES6 import and export statements. In CommonJS modules, all exported members are attached to the exports object, making it impossible for bundlers to know which parts are actually used, so the whole module ends up in the final bundle.

By rewriting a module in ES6 syntax, bundlers can determine the exact imports and drop the unused functions. The article demonstrates this with a simple math.js module that exports two functions, add1 and add2 , first using CommonJS and then using ES6:

// CommonJS version (math.js)
exports.add1 = function (x) { return x + 1; };
exports.add2 = function (x) { return x + 2; };

// ES6 version (math.js)
export function add1 (x) { return x + 1; }
export function add2 (x) { return x + 2; }

An app.js file imports the function:

import { add1 } from './math';
add1(100);

When bundled with Webpack using the default CommonJS version, both add1 and add2 appear in the output bundle because the tool cannot know that add2 is unused. After switching to the ES6 version, the bundle contains only the used add1 function, illustrating Tree Shaking in action.

To make an npm package tree‑shakable for downstream users, the article recommends adding a new pkg.module field to package.json that points to the ES6‑module build, while keeping the existing main field for the CommonJS build:

{
  "main": "dist/dist.js",
  "module": "dist/dist.es.js"
}

Bundlers that understand pkg.module (e.g., Rollup, newer Webpack versions) will prefer the ES6 build and enable Tree Shaking; older tools will fall back to the CommonJS build, preserving compatibility.

The article also shows a minimal Rollup configuration that outputs an ES module:

// rollup.config.js
export default {
  // ...other options
  output: {
    file: 'bundle.es.js',
    format: 'es'
  }
};

Finally, it notes that pkg.module is currently a proposal but has already been adopted by major bundlers, making it a practical way to ship packages that benefit from Tree Shaking without breaking existing workflows.