Diagnosing Rollup Tree‑Shaking Failures: A Practical Checklist

Recognizable Condition

After a production build you notice the bundle is larger than expected, or a source‑map shows code that your application never calls (e.g., lodash helpers or internal utilities). The bundle also contains /* @__PURE__ */ annotations that should have been stripped. This indicates Rollup’s tree‑shaking did not eliminate unused exports.

Common Causes – Quick Reference

Cause	Typical Symptom
Missing @rollup/plugin-commonjs or wrong order	Whole CommonJS modules appear in the bundle; named exports are not recognized.
Exporting via module.exports or export =	Module is treated as side‑effect only; no tree‑shaking.
Incorrect output.exports mode	Rollup cannot determine which exports are used; falls back to keeping everything.
Package.json sideEffects mis‑configured	Side‑effect flags prevent removal of code even if unused.
Missing or overridden /* @__PURE__ */ annotations	Helper functions remain in the bundle.

Ordered Checks

1. Verify the CommonJS plugin
   Run npm ls @rollup/plugin-commonjs to ensure it is installed. In rollup.config.js confirm it appears before other plugins that transform the code.
2. Inspect plugin order
   The order of plugins matters. commonjs must run before terser or any custom plugin that relies on ES module syntax.
3. Run Rollup in debug mode
   Execute

   rollup -c --debug
   

   Look for warnings such as Treating … as external or Skipping module … because it is marked as side‑effect only.
4. Check package side‑effects
   Open the package.json of each third‑party module you depend on and look for \"sideEffects\": false or an array. If the array lists files that contain side effects, Rollup will keep them.
5. Validate export syntax
   Search your source for export =, module.exports, or export default that is used where named exports are expected. Use export function foo() or export const bar = … instead.

Fixes Tied to Findings

• Add or reposition @rollup/plugin-commonjs
  In rollup.config.js:

  import commonjs from '@rollup/plugin-commonjs';\
  export default {\n  input: 'src/main.js',\n  plugins: [\n    commonjs(), // before other plugins\n    // ...\n  ],\n};
  

• Define named exports for opaque libraries
  If a library like lodash is imported as CommonJS and Rollup cannot infer named exports, add a namedExports map:

  commonjs({\n  namedExports: {\n    lodash: ['map', 'each']\n  }\n});
  

• Adjust output.exports mode
  For pure ES modules, set output.exports = 'named' to allow Rollup to track named usage.
• Mark libraries as side‑effect‑free
  If a dependency truly has no side effects, add \"sideEffects\": false to its package.json or override in your own config via sideEffects: false in the external field.
• Refactor imports to ES syntax
  Replace require('foo') with import foo from 'foo' where possible. This ensures Rollup treats the module as ES and can tree‑shake.

Verification Steps

1. Build with --silent
   

   rollup -c --silent
   

2. Analyze the bundle
   Run npm i -D rollup-plugin-visualizer and add it to the plugins list:

   import visualizer from 'rollup-plugin-visualizer';\nplugins: [\n  // ... other plugins\n  visualizer({ open: true })\n]\n

   The generated HTML shows a tree of modules; verify the suspect code is absent.
3. Compare gzipped sizes
   Use gzip -c dist/bundle.js | wc -c before and after the fix. A 5‑10 % reduction is a good indicator that tree‑shaking succeeded.
4. Check console warnings
   Re‑run with --debug and confirm no “treating … as external” warnings for the modules in question.

Escalation Criteria

If after applying all fixes the bundle remains larger than expected, consider:

• Opening an issue on the plugin’s repository with a minimal reproducible example; include the config and the console output.
• Enabling the experimental --experimentalOptimizeChunks flag to see if it improves the situation.
• Manually externalizing the problematic module by adding it to the external array in the config and verifying the size drop.
• Contacting the library maintainer to request a sideEffects update if the library incorrectly marks files as side‑effect‑free.

Practical Checklist Summary

• Confirm @rollup/plugin-commonjs is present and correctly ordered.
• Validate output.exports mode.
• Inspect third‑party sideEffects flags.
• Ensure exports use ES named syntax.
• Run visualizer and compare sizes.
• If unresolved, file a minimal issue or externalize the module.