rollup-plugin-purgecss

8.0.0 verified Mon Apr 27 auth: no javascript

Rollup plugin to remove unused CSS using PurgeCSS. Current stable version 8.0.0. Part of the PurgeCSS monorepo, releases follow PurgeCSS core releases. Key differentiator: tree-shaking CSS in Rollup bundles based on content analysis, supporting safelisting, extractors, and CSS variables. Compatible with Rollup 2+, ESM-first with TypeScript types. Regular releases with breaking changes across major versions. Alternative to cssnano and uncss for unused CSS removal.

Common errors

error Error: Cannot find module 'rollup-plugin-purgecss' ↓

cause Package not installed or not in node_modules.

fix

npm install rollup-plugin-purgecss --save-dev

error TypeError: purgecss is not a function ↓

cause Using CommonJS require style with default export in ESM-only version.

fix

Use import purgecss from 'rollup-plugin-purgecss'; (ESM) or const { default: purgecss } = require('rollup-plugin-purgecss');

error The 'purgecss' option 'whitelist' is not supported ↓

cause Using deprecated whitelist option from v2.x or earlier.

fix

Replace whitelist with safelist; see migration guide to v3.

error Error: PostCSS plugin cannot be imported via named export; use default import. ↓

cause Using import { purgeCSSPlugin } from '@fullhuman/postcss-purgecss' in v8.0.0.

fix

Use import purgeCSSPlugin from '@fullhuman/postcss-purgecss';

Warnings

breaking Import of the PostCSS plugin changed in v8.0.0. Must use default import. ↓

fix import purgeCSSPlugin from '@fullhuman/postcss-purgecss';

breaking Drop PostCSS 7 support in v4.0.0, use @fullhuman/postcss-purgecss 3.0 for PostCSS 7. ↓

fix Upgrade to PostCSS 8 or use @fullhuman/postcss-purgecss@3 if stuck.

deprecated Whitelist options renamed to safelist in v3.0.0. Old whitelist, whitelistPatterns, etc. no longer work. ↓

fix Use safelist option with standard, deep, greedy arrays as documented.

gotcha Plugin does not automatically re-run when watched files change; requires Rollup's watch mode or manual rebuild. ↓

fix Use Rollup's --watch flag or configure watch options.

gotcha Pseudo-classes like :where, :not, :is could be incorrectly removed in older versions; fixed in v7.0.2. ↓

fix Update to v7.0.2 or later.

Install

npm install rollup-plugin-purgecss

yarn add rollup-plugin-purgecss

pnpm add rollup-plugin-purgecss

Imports

default (purgecss)

wrong

const purgecss = require('rollup-plugin-purgecss');

correct

import purgecss from 'rollup-plugin-purgecss';

Default import works for ESM. CommonJS require is not recommended in v8+.

type PurgecssOptions

wrong

import { PurgecssOptions } from 'rollup-plugin-purgecss';

correct

import type { PurgecssOptions } from 'rollup-plugin-purgecss';

Use type-only import for better tree-shaking.

PurgeCSS (core)
wrong
```
import PurgeCSS from 'rollup-plugin-purgecss';
```
correct
```
import PurgeCSS from 'purgecss';
```
The rollup plugin re-exports nothing else; for core PurgeCSS API use 'purgecss' package directly.

Quickstart

Basic Rollup configuration using purgecss plugin with safelist and CSS variable removal.

import { rollup } from 'rollup';
import purgecss from 'rollup-plugin-purgecss';

await rollup({
  input: 'src/main.js',
  plugins: [
    purgecss({
      content: ['index.html', 'src/**/*.js'],
      safelist: {
        standard: ['safelisted-class'],
        deep: [/^safelisted-/],
        greedy: [/^greedy-/]
      },
      variables: true
    })
  ],
  output: {
    dir: 'dist',
    format: 'es'
  }
});