Registry / devops / rollup-plugin-purgecss

rollup-plugin-purgecss

library8.0.0jsnpmunverified

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.

devops

npm install rollup-plugin-purgecss

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ROLLUP-PLUGIN-PURG

rollup-plugin-purgecss

devopsjavascriptv8.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (purgecss)

✓ import purgecss from 'rollup-plugin-purgecss';

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

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

type PurgecssOptions

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

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

Use type-only import for better tree-shaking.

PurgeCSS (core)

✓ import PurgeCSS from 'purgecss';

✗ import PurgeCSS from 'rollup-plugin-purgecss';

The rollup plugin re-exports nothing else; for core PurgeCSS API use 'purgecss' package directly.

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' } });

Debug

Known issues

breakingImport of the PostCSS plugin changed in v8.0.0. Must use default import.

fix

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

affects: =8.0.0

breakingDrop 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.

affects: >=4.0.0

deprecatedWhitelist 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.

affects: >=3.0.0

gotchaPlugin 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.

affects: >=6.0.0

gotchaPseudo-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.

affects: <7.0.2

Errors

Common errors & fixes

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

Package not installed or not in node_modules.

fix

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

TypeError: purgecss is not a function

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');

The 'purgecss' option 'whitelist' is not supported

Using deprecated whitelist option from v2.x or earlier.

fix

Replace whitelist with safelist; see migration guide to v3.

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

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

fix

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

Upgrade

Version history

8.0.0latest on npm

Audit

Dependencies

purgecssrequiredCore library for CSS purging

rolluprequiredPeer dependency, must be installed separately

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/FullHuman/purgecss ↗

packagehttps://www.npmjs.com/package/rollup-plugin-purgecss ↗

homepagehttps://purgecss.com ↗