Rollup tree shaking behavior with sideEffects property in nested dependencies

Short answer

Rollup respects the sideEffects flag on a per‑package basis. When a package declares "sideEffects": false, any import from that package is considered pure unless the import itself is used for its side effects. Dynamic imports are treated conservatively: if a module is only imported via import() and the package is marked side‑effect‑free, Rollup will keep all of that module’s exports. The /*@__PURE__*/ comment only marks an individual function call as pure; it does not override a package’s sideEffects setting or cause Rollup to retain a module that would otherwise be pruned.

How Rollup applies the sideEffects flag

• Rollup walks the module graph and, for each imported file, looks up the nearest package.json that encloses the file.
• If that package.json contains "sideEffects": false, the importer assumes the file has no global side effects.
• Only imports that are used for their side effects (e.g., import './init.js';) are kept if the package declares side‑effect‑free.

Dynamic imports

Dynamic imports are considered “potentially executed at runtime.” Rollup therefore errs on the side of safety: it keeps every export of the target module unless the package’s sideEffects flag is false and the dynamic import is explicitly used for its side effects. In practice, this means that a module that registers a polyfill inside a sideEffects: false package will survive the tree‑shake only if you import it directly or if the dynamic import is used for its side effects.

/*@__PURE__*/ annotations

The comment is a hint to the minifier that a specific function call has no observable side effects. It does not influence Rollup’s module‑level tree‑shaking decisions. A /*@__PURE__*/‑marked call will be removed if the function is unused, but the module containing that function will still be dropped if its package declares sideEffects: false and the module is never imported for its side effects.

Practical steps to verify and control behavior

1. Run Rollup with the --verbose flag to see which modules are kept. Look for entries that come from the nested dependency in question.
2. If a required initialization module is missing, import it explicitly (e.g., import 'dep/init.js';) or expose a dedicated init entry point in the dependency.
3. If you want the dependency to be treated as side‑effect‑full, change its package.json to "sideEffects": true or remove the flag entirely.
4. Use --no-treeshake to confirm that tree shaking is the cause of the missing code.
5. When minifying, confirm that pure annotations are respected by bundling a function call marked /*@__PURE__*/ and verifying it disappears when unused.

What to do if you need side‑effect modules

• Expose a separate entry point that performs the necessary initialization and import that entry point in your application.
• Alternatively, keep the sideEffects flag set to true for the dependency if you cannot modify its package.json.
• If the dependency is a third‑party package, consider forking it or contacting the maintainer to add an explicit init entry.

Missing diagnostic detail?

Does your code rely on a dynamic import that only triggers a side‑effect module, or do you import a specific function from that module? The answer will influence whether the module can be safely pruned or must be imported explicitly.