# CSS purging and tree-shaking configured

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

## Why it matters

Tailwind CSS ships with thousands of utility classes by default. Without purging, the full Tailwind stylesheet is 3–4MB uncompressed (150–200KB gzipped). A project that actually uses 200 classes ships the other 99% as dead CSS, adding meaningful parse time and network cost on every page load. ISO 25010:2011 resource-utilisation targets this waste; the user-facing effect is a heavier initial render with no corresponding functionality.

## Severity rationale

Low because unused CSS adds network and parse overhead, but the user-visible delay is typically under 200ms and does not block interactivity unless the CSS bundle is especially large.

## Remediation

Configure Tailwind's `content` array to point at every file that generates class names. Tailwind scans these paths and strips unused selectors before production build.

```js
// tailwind.config.js
module.exports = {
  content: [
    './app/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
    './lib/**/*.{ts,tsx}',
  ],
  theme: { extend: {} },
  plugins: [],
}
```

After configuring, run `npm run build` and check the CSS bundle size in `.next/static/css/` — it should be well under 50KB gzipped.

## Detection

- **ID:** `css-purging-enabled`
- **Severity:** `low`
- **What to look for:** Count all CSS files in the build output. Measure their combined gzipped size. If the project uses Tailwind CSS, check `tailwind.config.js` for the `content` or `purge` field. If using other CSS-in-JS or SCSS, look for PostCSS purge plugins. Measure the final CSS bundle size (in `dist/` or build output).
- **Pass criteria:** CSS purging is configured. Unused selectors are removed from the final CSS. The final CSS bundle is under 50KB gzipped.
- **Fail criteria:** CSS purging is not configured, or the final CSS bundle exceeds 50KB gzipped.
- **Skip (N/A) when:** The project uses no CSS framework or uses dynamically-generated CSS that cannot be statically purged.

- **Cross-reference:** For overall bundle size including CSS, see the `bundle-size-critical` check.
- **Detail on fail:** `"Tailwind CSS not configured with content purge — all Tailwind selectors included in bundle (187KB gzipped)"` or `"CSS bundle is 84KB gzipped, including unused utility classes"`
- **Remediation:** For Tailwind CSS, configure the content field to tell Tailwind which files to scan for used classes.

  ```js
  // tailwind.config.js — configure content purge paths
  module.exports = { content: ['./app/**/*.{ts,tsx}', './components/**/*.{ts,tsx}'] }
  ```

---

## External references

- iso-25010 performance-efficiency.resource-utilization

Taxons: performance

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