# Build tool supports tree shaking (no barrel file issues)

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

## Why it matters

Barrel files that re-export every module in a directory prevent the build tool from eliminating dead code — even when you only import one function, the bundler may include the entire barrel. A `lib/index.ts` that re-exports 50 utilities causes every importer to pull in all 50, regardless of usage. Without `sideEffects: false` in `package.json`, the bundler cannot safely drop any of those exports. On large codebases, this pattern adds tens to hundreds of kilobytes to the bundle that serve no user-visible function. ISO 25010 performance-efficiency.resource-utilization identifies this as avoidable resource inclusion.

## Severity rationale

Low because tree-shaking issues rarely cause visible failures but silently add unnecessary payload, compounding with other bundle-size problems.

## Remediation

Set `sideEffects: false` in `package.json` to signal the bundler that modules can be safely dropped when unused. Reduce or eliminate barrel files with more than 10 re-exports, replacing them with direct imports.

```json
// package.json
{
  "sideEffects": false
}
```

```ts
// Before — barrel file prevents tree shaking
// lib/index.ts
export * from './utils/date'
export * from './utils/string'
export * from './hooks/useCounter'
export * from './hooks/useDebounce'
export * from './components/Button'
// ...40 more

// After — import directly from the module
import { formatDate } from '@/lib/utils/date'
import { useCounter } from '@/lib/hooks/useCounter'
```

For monorepos, also set `sideEffects: false` in each package's `package.json`, not just the root.

## Detection

- **ID:** `tree-shaking`
- **Severity:** `low`
- **What to look for:** Count all barrel files (index.ts/index.js that re-export from other modules) in the project. For each barrel file, count the number of re-exports. Check for `sideEffects: false` in `package.json`, or examine build config for tree-shaking enablement. Modern frameworks like Next.js enable tree-shaking by default. Enumerate: "X barrel files found with Y total re-exports."
- **Pass criteria:** The build tool supports tree shaking (verified by `sideEffects: false` in package.json or framework default), and no barrel file re-exports more than 20 items without the module being fully consumed. No more than 3 barrel files exist that re-export 10+ items. Report: "X barrel files found, largest re-exports Y items. Tree shaking enabled via [mechanism]."
- **Fail criteria:** Tree shaking is disabled (explicit `sideEffects: true` in package.json or build tool configured without tree shaking), or more than 3 barrel files each re-export 10+ items without proper configuration.
- **Skip (N/A) when:** Never — tree shaking reduces bundle size.
- **Detail on fail:** `"package.json has sideEffects: true — prevents tree shaking across 5 barrel files with 80+ total re-exports"` or `"4 barrel files in lib/ re-export 15+ items each — prevents unused export elimination"`
- **Remediation:** Enable tree shaking:

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

  Minimize barrel files:

  ```ts
  // Before — barrel file prevents tree shaking
  // lib/index.ts
  export * from './utils'
  export * from './hooks'
  export * from './components'

  // After — granular imports
  // Only import what you need
  import { useCounter } from './hooks/useCounter'
  import { formatDate } from './utils/date'
  ```

## External references

- iso-25010 performance-efficiency.resource-utilization

Taxons: performance

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