# Tree-shaking enabled

- **Pattern:** `ab-002392` (`sdk-package-quality.build-distribution.tree-shaking`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002392
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002392)

## Why it matters

Without `"sideEffects": false` in `package.json`, webpack and Rollup conservatively assume every module in your package has side effects and include all of it in every consumer bundle. Even if the consumer only calls one function, they get the entire package. ISO 25010 resource-utilization is directly impacted: consumers pay the full bundle cost regardless of actual usage. CJS-only output compounds this — tree-shaking is an ESM feature, so CJS packages cannot be tree-shaken at all, regardless of the `sideEffects` declaration.

## Severity rationale

High because the absence of `sideEffects: false` causes all major bundlers to include the entire package in consumer builds, even when only a fraction of the API is used.

## Remediation

Declare `sideEffects: false` in `package.json` and ensure the package outputs ESM.

```json
{ "sideEffects": false }
```

If specific files have legitimate side effects (CSS imports, global polyfills), list only those:

```json
{ "sideEffects": ["./dist/styles.css"] }
```

Tree-shaking requires three things together: ESM output format, named exports, and the `sideEffects` declaration. All three must be present. Verify with `rollup --input dist/index.mjs --file out.js` and check whether unused exports appear in the output.

## Detection

- **ID:** `tree-shaking`
- **Severity:** `high`
- **What to look for:** List all exports and verify tree-shaking support. check for tree-shaking support:
  1. `"sideEffects": false` in `package.json` (tells bundlers the package is safe to tree-shake)
  2. ESM output format (CJS cannot be tree-shaken)
  3. No barrel files that re-export everything (`export * from` chains that defeat tree-shaking)
  4. Named exports instead of a single default namespace object
  5. No module-level side effects in source files
- **Pass criteria:** The package declares `"sideEffects": false` (or a targeted `sideEffects` array) in `package.json`, provides ESM output, and uses named exports. Bundlers can eliminate unused exports — package.json must include sideEffects: false or a specific file list for 100% tree-shaking support. Report: "X exports found, tree-shaking supported via sideEffects field."
- **Fail criteria:** No `sideEffects` field in `package.json`, AND the package outputs only CJS format, AND/OR uses a single default export containing all functionality.
- **Skip (N/A) when:** The package is designed to be used in Node.js only (not bundled for browsers) and has a single export that is always used in full. Also skip for Go, Rust, and Python (tree-shaking is a JavaScript bundler concept).
- **Detail on fail:** `"No sideEffects field in package.json. Build output is CJS only. Bundlers like webpack and rollup cannot tree-shake unused exports — consumers get the entire package even if they use one function."`
- **Remediation:** Tree-shaking removes unused code from consumer bundles. Three things enable it:

  ```json
  // package.json — declare no side effects:
  {
    "sideEffects": false
  }
  ```

  If some files DO have side effects (e.g., CSS imports), use an array:
  ```json
  { "sideEffects": ["./dist/styles.css"] }
  ```

  Ensure ESM output (tree-shaking only works with ES modules) and use named exports.

## External references

- iso-25010 performance-efficiency.resource-utilization
- iso-25010 compatibility.interoperability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-002392