Namespace imports retain full module despite package.json sideEffects: false

Direct Answers

1. No. treeshake.moduleSideEffects (boolean or function) controls whether a whole module is retained, but it cannot make individual property reads on a namespace object statically analyzable. No plugin hook exposes the tree-shaker’s internal namespace-opacity logic.
2. Setting treeshake.propertyReadSideEffects: false globally enables more aggressive removal, but it is not safe by default. It assumes all property reads are pure, which breaks packages that use getters with side effects or rely on runtime property enumeration (e.g., Object.keys(ns)).
3. No such mechanism exists in Rollup 4.x. sideEffects as a file-glob array gives fine-grained module retention, but namespace imports remain opaque. The only reliable way to get elimination today is to avoid import * as ns and use named imports instead.

Why Namespace Imports Are Opaque

Rollup’s tree-shaker works by building a static dependency graph. A namespace import (import * as ns from 'pkg') creates a single binding whose properties are accessed dynamically (ns.foo, ns['bar']). Because JavaScript allows computed property keys and with-style dynamic access, the tree-shaker cannot prove which exports are actually used without whole-program analysis that Rollup does not perform. The sideEffects: false flag only tells Rollup “this module has no top-level side effects, so drop it if nothing imports it.” It does not say “every export of this module is pure and can be individually eliminated through a namespace object.”

Confirmed Behavior (Rollup 4.x)

• sideEffects: false → module dropped if no import reaches it.
• Any namespace import reaches the module → module retained.
• All exports of that module become reachable through the namespace → all retained.
• treeshake.propertyReadSideEffects: true (default) reinforces this by assuming ns.prop might trigger a getter.
• treeshake.moduleSideEffects: 'no-external' or a function can override retention for specific modules, but the opacity of the namespace object remains.

Practical Steps for Your Case

1. Audit the dependency. Confirm the package truly has no getters, proxies, or Object.defineProperty tricks on its exports. If it’s a plain re-export barrel, named imports are safe.
2. Refactor call sites. Replace import * as ns from 'pkg' with import { used } from 'pkg' for each binding you actually use. This is the only change that guarantees elimination.
3. If you must keep namespace imports (e.g., dynamic ns[methodName]() patterns), accept that the whole module stays. You can verify with rollup --config --plugin rollup-plugin-visualizer to see retained exports.
4. Do not set propertyReadSideEffects: false globally unless you have audited every dependency for getter side effects.

One Diagnostic Detail

Does your codebase use computed property access on the namespace object (e.g., ns[dynamicKey], Object.keys(ns), or for (const k in ns))? If yes, named imports cannot replace the namespace import without runtime logic changes, and the module will correctly remain un-shaken.