What does `"sideEffects": false` in a package's package.json actually claim, and what goes wrong when a package makes that claim untruthfully?

## Why the field exists Deciding whether evaluating a module is observable is undecidable in general, so bundlers default to keeping any module they cannot prove inert. That default is correct and expensive: it means an unmarked package's modules survive even when you import nothing from them. `sideEffects` is the escape hatch — a way for the package author, who actually knows, to assert what the tool cannot derive. It is worth being precise about the status of the field: it is not standardised, Node ignores it entirely, and it has nothing to do with `exports`, `type`, or resolution. webpack introduced it and other bundlers adopted it; Rollup honours it through its node-resolve plugin, and esbuild, Vite and Parcel read it too. Treat it as an ecosystem convention with broad support, not a language feature. ## The three shapes ```json { "sideEffects": false } ``` No file in this package does anything observable on evaluation. If none of a module's exports are used, the import may be removed and the module never evaluated. ```json { "sideEffects": ["*.css", "./src/polyfills.js", "./src/register-*.js"] } ``` These globs, relative to the package root, name the files that *do* have effects; those are always evaluated when imported. Everything else is treated as pure. This is the shape most real libraries should use, because almost every library has at least one such file. ```json { } ``` Field absent, or `true`. Assume every file has effects. Safe, and the reason unmarked dependencies bloat bundles. ## What the claim licenses, precisely The claim is about *evaluation*, not about the code's usefulness. It licenses exactly one transformation: when an importer ends up using none of the bindings a module provides, delete the import edge rather than keeping the module for its effects. It does not license deleting used exports, does not make impure functions safe to call, and does not apply to the effects of *calling* the package's API — only to what happens at import time. Note also that the flag governs the files of the package that declares it. Declaring it in your application's own `package.json` makes the same claim about your application's source files, which is a much stronger statement than most teams realise when they copy the line in. ## How a false claim fails The failures share a shape: the build succeeds, tests that import the module directly still pass, dev mode looks fine (because dev builds usually skip elimination), and the production bundle is quietly missing behaviour. - **Polyfills.** `import 'core-js/stable'` or a module patching `Array.prototype` is removed; older engines throw `TypeError` on a missing method at runtime. - **Styles.** `import './theme.css'` is removed and the UI ships unstyled — the classic symptom that sends people looking at the CSS pipeline instead of the flag. - **Registration.** `customElements.define(...)`, plugin registries, i18n message bundles and route tables that register on import silently never register; components never upgrade, routes 404. - **Singletons and instrumentation.** A module-level client, error handler or performance mark that was installed at import time simply is not there. The trace is unpleasant because the missing code left no trace: there is no error at build time, no warning, and the stack trace at runtime points at the *consumer* of the missing behaviour, not at the module that was deleted. ## Auditing your own package Before adding the flag, read every module body and ask what a consumer could observe if it never ran. In practice: 1. Grep for top-level statements that are not declarations — assignments, calls, `new`, `throw`. 2. Check for imports of CSS or other assets. 3. Check for anything that mutates imported or global state. 4. List every file that fails and put it in the array form rather than dropping the flag entirely. Then verify empirically: build a small consumer that imports one trivial export, inspect the output for the modules you expect to be gone, and run the app. ## Interview framing The strong answer says three things: what the claim means operationally (skip evaluation of unused modules), that nothing checks it, and what the failure mode looks like (production-only missing behaviour). The weak answer describes it as "a flag that makes tree shaking work", which mistakes a hand-written assertion for an analysis.