How to Optimize NPM Package Bundles: Tree‑Shaking, Babel, and Side‑Effects Explained

Why Bundle Output Matters

When publishing a third‑party library, developers must decide which module formats to emit (CommonJS, UMD, ESModule) and whether to bundle or simply transpile with Babel. ESModules are recommended as the primary format because they enable tree‑shaking, while other formats can be added based on target environments.

Tree‑Shaking Fundamentals

Tree‑shaking removes dead code by analyzing export usage. In Webpack 5, the process involves:

Identifying provided exports ( providedExports).

Detecting used exports via usedExports, sideEffects, and terser.

Concatenating used modules (scope hoisting) with concatenateModules.

Registering used exports in __webpack_exports__; unused exports are eliminated by the minifier.

Two key concepts affect the result:

ConcatenateModules – merges used modules into a single closure, reducing bundle size and runtime overhead.

SideEffects – marks modules that may have side effects; setting sideEffects: false allows Webpack to skip entire modules when none of their exports are used.

Practical Experiments

Using a simple calculator library, the article shows:

With sideEffects: false, unused modules (e.g., Processor.js) are stripped, while modules with side‑effectful code retain necessary parts.

Adding /*#__PURE__*/ comments enables function‑level dead‑code elimination.

Wrapping global property accesses in IIFEs further reduces retained code.

Babel Configuration and Polyfills

Babel handles two tasks: transpiling newer syntax and injecting polyfills via core‑js. The article compares two setups:

@babel/preset‑env with useBuiltIns: "usage" automatically adds needed polyfills but may over‑inject.

@babel/plugin‑transform‑runtime moves helpers to @babel/runtime and provides sandboxed polyfills, reducing duplication.

Examples show the generated code for both configurations, highlighting differences in helper inclusion and polyfill handling.

Combining Tree‑Shaking and Babel

When an ESModule library is bundled with Webpack, Babel‑added helpers and polyfills become part of the final bundle, even if only a single export is used. Setting sideEffects: false in the library’s package.json can prune unused polyfills, but this is not a universal solution.

Strategies for Reducing Bundle Bloat

Prefer ESModule output.

Keep modules pure (only import and export).

Declare side‑effects accurately in package.json.

Use /*#__PURE__*/ for functions without side effects.

Wrap global variable accesses in IIFEs.

Additional approaches include explicit polyfill documentation, using framework‑specific plugins (e.g., Vue CLI’s Babel plugin), splitting the library into multiple entry files, or distributing source code and letting the consumer’s build pipeline handle transpilation.

Conclusion

The article consolidates common pain points when building npm packages, demonstrates concrete configurations and code examples, and offers practical recommendations to achieve smaller, more tree‑shakable bundles.