Glossary / Side-effect annotations

Side-effect annotations

Side-effect annotations tell a bundler whether evaluating a module or particular expression can change observable behavior. They help dead-code elimination discard unused code safely, but false claims can remove required initialization and cause subtle production-only failures.

Module-level metadata

A package can declare "sideEffects": false in package.json to claim imports of its files have no observable effects, allowing a bundler to omit unused modules. An array of glob patterns can identify files that do have effects, such as CSS imports or polyfills. This metadata is a contract to tools; it does not change JavaScript runtime semantics.

A module may export pure functions but still have import-time effects: registering custom elements, patching globals, installing locales, or importing CSS. Conversely, effectful functions do not execute merely because their module is loaded; the annotation concerns whether the module can be safely dropped when exports are unused.

Some bundlers support expression-level annotations such as /*#__PURE__*/ around calls or constructors. This asserts the call's result can be discarded when unused. If the call has effects beyond its result, the assertion is unsound. Syntax and support vary by bundler and minifier.

Engineering guidance

Audit initialization paths before setting metadata. Keep effects in explicit entry modules and list exceptions precisely. Test production builds with features that depend on registration or styles. Treat annotations as correctness-sensitive code, review changes, and inspect output after tool upgrades.

Interview questions

  1. Does sideEffects: false prevent effects at runtime? No; it tells bundlers unused modules may be removed.
  2. What if the declaration is false? Required initialization can disappear from optimized builds.
  3. What is a pure-call annotation? A tool hint that an unused result can be removed; it must not hide observable effects.
  4. Why list CSS as side-effectful? Styles may be required without any referenced JavaScript export.
  5. How validate metadata? Build and run production output along paths relying on initialization, styles, or registration.

References