PurgeCSS — Remove Unused CSS from Your Builds

Introduction

PurgeCSS scans your HTML, JavaScript, Vue, and other template files to identify which CSS selectors are actually used. It then removes all unused selectors from your stylesheets, often reducing CSS file sizes by 80-95% when used with large utility frameworks.

What PurgeCSS Does

• Analyzes content files (HTML, JSX, Vue, Svelte, PHP, etc.) for CSS class references
• Removes any CSS selectors not found in the content analysis
• Supports multiple extractors for different template syntaxes
• Integrates as a PostCSS plugin, webpack plugin, or CLI tool
• Allows safelisting selectors that should never be removed

Architecture Overview

PurgeCSS works in three phases: extraction, comparison, and removal. Extractors parse content files to produce a list of used selectors. The CSS parser (based on PostCSS) walks the stylesheet AST and marks each selector as used or unused based on the extracted list. Unused rules are stripped from the output. Custom extractors can be written for any template syntax.

Self-Hosting & Configuration

• Install via npm: npm install purgecss (library) or npm install -g purgecss (CLI)
• Use as a PostCSS plugin with @fullhuman/postcss-purgecss
• Integrate with webpack via purgecss-webpack-plugin
• Configure content globs and safelist patterns in the config object
• Add safelist entries for dynamically generated class names that static analysis cannot detect

Key Features

• Reduces CSS bundles by up to 95% when paired with utility frameworks like Tailwind or Bootstrap
• Pluggable extractor system handles JSX, Vue SFCs, Pug, and other template formats
• Safelisting supports exact class names, patterns, and deep selectors
• Works in any Node.js build pipeline or as a standalone CLI
• Framework-agnostic — processes any CSS regardless of how it was generated

Comparison with Similar Tools

• Tailwind CSS JIT — Tailwind v3+ generates only used utilities at build time; PurgeCSS works with any CSS source
• UnCSS — renders pages in a headless browser; PurgeCSS uses static analysis, which is faster
• cssnano — minifies CSS (whitespace, shorthand) but does not remove unused selectors
• PurifyCSS — predecessor project, now unmaintained; PurgeCSS is the active successor
• Lightning CSS — fast CSS transformer and minifier; does not remove unused rules

FAQ

Q: Does PurgeCSS work with Tailwind CSS? A: Yes, though Tailwind v3+ has its own JIT engine that generates only used classes. PurgeCSS is still useful with Tailwind v2 or custom CSS frameworks.

Q: Will PurgeCSS remove CSS used by JavaScript-injected classes? A: It might, because static analysis cannot see runtime-generated class names. Add such classes to the safelist configuration.

Q: Can I use PurgeCSS with Sass or Less? A: Run PurgeCSS on the compiled CSS output, not on the Sass or Less source files.

Q: How do I handle third-party component library styles? A: Safelist the library's class name patterns or point PurgeCSS at the library's source files as additional content.

Sources

• https://github.com/FullHuman/purgecss
• https://purgecss.com/