Rollup 4.x sideEffects: false package declaration vs unannotated module side effects

Direct answer

Rollup 4.x does not let a package-level "sideEffects": false suppress top-level statements in modules that are actually imported. The flag only tells the treeshaker that unused exports can be dropped safely. If a module is kept because at least one export is used, its top-level code (console.log, global mutations, etc.) still runs.

The treeshake.moduleSideEffects option changes how external packages are treated. With the default "if-removed", a dependency that declares sideEffects: false but contains unannotated side effects will be preserved—and those side effects will execute—as soon as any export is retained. Setting moduleSideEffects: false forces Rollup to treat all externals as side-effect-free, which can incorrectly eliminate modules that do have real side effects.

To verify which modules were eliminated without relying on source maps, use a build-time plugin that logs the final module graph (e.g., a buildEnd hook writing this.getModuleIds() to a file) or run rollup-plugin-visualizer and inspect the generated tree.

How the signals interact

Package-level sideEffects: false

• Acts as a global hint that every module in the package is pure.
• Allows Rollup to drop unused exports from imported modules without fear of losing side effects.
• Does not prevent top-level statements in a module that is imported from executing.

Module-level top-level statements

• Run whenever the module is included in the bundle graph.
• Are only removed if the entire module becomes unreachable (no live exports, no importers).
• Annotations like /* @__PURE__ */ on individual expressions give finer-grained control but are not required for the package flag to work.

treeshake.moduleSideEffects settings

Reliable verification (no source maps)

1. Custom plugin with buildEnd hook

   // rollup.config.js
   import { writeFileSync } from 'fs';
   export default {
     plugins: [{
       name: 'module-audit',
       buildEnd() {
         const ids = this.getModuleIds();
         writeFileSync('module-graph.json', JSON.stringify(ids, null, 2));
       }
     }]
   };
   

   Run a clean build (rm -rf node_modules/.cache && rollup -c) and compare module-graph.json against the expected module list.

2. rollup-plugin-visualizer

   npm i -D rollup-plugin-visualizer
   # add to plugins: visualizer({ open: true })
   

   Modules absent from the generated treemap were eliminated.

3. Runtime smoke test

   Add a unique console.log('MODULE_X_LOADED') to a module you expect to be dropped. Run the bundle; if the log never appears, the module was removed.

Caveats to watch

• Rollup 4.x ignores the webpack-style array syntax "sideEffects": ["*.css"]; only boolean false is respected.
• Watch mode caches the module graph. If package.json sideEffects changes, restart the watch process.
• Monorepos with hoisted node_modules may cause Rollup to read a different package.json, altering side-effect assumptions.

One missing detail

What value is currently configured for treeshake.moduleSideEffects in your Rollup config? The recommendation changes if you have overridden the default "if-removed".