# Tree-shaking enabled and verified

- **Pattern:** `ab-002022` (`performance-deep-dive.bundle-analysis.tree-shaking-enabled`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002022
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002022)

## Why it matters

When tree-shaking is disabled or ineffective, every utility your bundler pulls in ships in full — including the 95% of lodash or date-fns that your code never calls. On a typical project that imports from 10–15 large libraries, inactive tree-shaking can add 200–400KB of dead code to the production bundle. ISO 25010:2011 resource-utilisation captures the storage and bandwidth waste; the user-facing cost is slower parse and execution time on every visit.

## Severity rationale

High because ineffective tree-shaking silently inflates the production bundle with unused code, adding hundreds of kilobytes that slow parse time for every visitor without any obvious error signal.

## Remediation

Switch to ES module named imports for every large dependency and ensure your build runs in production mode. Add `"sideEffects": false` to your own `package.json` so downstream bundlers can tree-shake your code too.

```js
// Before (imports all of lodash)
import _ from 'lodash'

// After (tree-shakeable — only debounce bundled)
import { debounce } from 'lodash-es'
```

In `package.json`, add:
```json
{ "sideEffects": false }
```

## Detection

- **ID:** `tree-shaking-enabled`
- **Severity:** `high`
- **What to look for:** Count all dependencies in `package.json` that support tree-shaking. Enumerate which have `"sideEffects": false` or use ES module exports. Check the build configuration for tree-shaking settings. In webpack, verify `mode: 'production'` is set. In Vite and Rollup, check `rollupOptions.output.format`. Look for dependencies marked as side-effect-free in their package.json (`"sideEffects": false`). Use bundle analyzer to confirm that unused exports from dependencies are not included in the final bundle.
- **Pass criteria:** The build system is configured with tree-shaking enabled (production mode or explicit configuration). Bundle analyzer confirms that unused exports from dependencies are not included. At least 80% of large dependencies should use ES module imports for effective tree-shaking.
- **Fail criteria:** Build is in development mode or tree-shaking is explicitly disabled. Unused exports from dependencies are present in the final bundle.
- **Skip (N/A) when:** Never — tree-shaking should apply to all production builds.

- **Cross-reference:** For vendor chunk separation, see the `vendor-chunks-split` check in this category.
- **Detail on fail:** `"Build configured with mode: 'development' — tree-shaking inactive"` or `"Bundle includes unused lodash utilities; package.json does not mark lodash as sideEffects: false, and import { debounce } from 'lodash' is used but other utilities are bundled"`
- **Remediation:** Tree-shaking removes unused code at build time. Ensure your build configuration uses production mode and enables tree-shaking. For dependencies, use ES modules with named imports instead of default imports (e.g., `import { debounce } from 'lodash-es'` rather than `import _ from 'lodash'`). Mark your package as side-effect-free in package.json: `"sideEffects": false`. This tells bundlers they can safely remove unused imports.

  ```js
  // package.json — mark your package as side-effect-free
  { "sideEffects": false }
  // Use named imports: import { debounce } from 'lodash-es' in src/utils/helpers.ts
  ```

## External references

- iso-25010 time-behaviour
- iso-25010 performance-efficiency.resource-utilization

Taxons: performance

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