{"id":27359,"library":"rollup-plugin-purgecss","title":"rollup-plugin-purgecss","description":"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.","status":"active","version":"8.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/FullHuman/purgecss","tags":["javascript","rollup-plugin","purgecss","remove","unused","css","typescript"],"install":[{"cmd":"npm install rollup-plugin-purgecss","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-purgecss","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-purgecss","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for CSS purging","package":"purgecss","optional":false},{"reason":"Peer dependency, must be installed separately","package":"rollup","optional":false}],"imports":[{"note":"Default import works for ESM. CommonJS require is not recommended in v8+.","wrong":"const purgecss = require('rollup-plugin-purgecss');","symbol":"default (purgecss)","correct":"import purgecss from 'rollup-plugin-purgecss';"},{"note":"Use type-only import for better tree-shaking.","wrong":"import { PurgecssOptions } from 'rollup-plugin-purgecss';","symbol":"type PurgecssOptions","correct":"import type { PurgecssOptions } from 'rollup-plugin-purgecss';"},{"note":"The rollup plugin re-exports nothing else; for core PurgeCSS API use 'purgecss' package directly.","wrong":"import PurgeCSS from 'rollup-plugin-purgecss';","symbol":"PurgeCSS (core)","correct":"import PurgeCSS from 'purgecss';"}],"quickstart":{"code":"import { rollup } from 'rollup';\nimport purgecss from 'rollup-plugin-purgecss';\n\nawait rollup({\n  input: 'src/main.js',\n  plugins: [\n    purgecss({\n      content: ['index.html', 'src/**/*.js'],\n      safelist: {\n        standard: ['safelisted-class'],\n        deep: [/^safelisted-/],\n        greedy: [/^greedy-/]\n      },\n      variables: true\n    })\n  ],\n  output: {\n    dir: 'dist',\n    format: 'es'\n  }\n});","lang":"typescript","description":"Basic Rollup configuration using purgecss plugin with safelist and CSS variable removal."},"warnings":[{"fix":"import purgeCSSPlugin from '@fullhuman/postcss-purgecss';","message":"Import of the PostCSS plugin changed in v8.0.0. Must use default import.","severity":"breaking","affected_versions":"=8.0.0"},{"fix":"Upgrade to PostCSS 8 or use @fullhuman/postcss-purgecss@3 if stuck.","message":"Drop PostCSS 7 support in v4.0.0, use @fullhuman/postcss-purgecss 3.0 for PostCSS 7.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use safelist option with standard, deep, greedy arrays as documented.","message":"Whitelist options renamed to safelist in v3.0.0. Old whitelist, whitelistPatterns, etc. no longer work.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Use Rollup's --watch flag or configure watch options.","message":"Plugin does not automatically re-run when watched files change; requires Rollup's watch mode or manual rebuild.","severity":"gotcha","affected_versions":">=6.0.0"},{"fix":"Update to v7.0.2 or later.","message":"Pseudo-classes like :where, :not, :is could be incorrectly removed in older versions; fixed in v7.0.2.","severity":"gotcha","affected_versions":"<7.0.2"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"npm install rollup-plugin-purgecss --save-dev","cause":"Package not installed or not in node_modules.","error":"Error: Cannot find module 'rollup-plugin-purgecss'"},{"fix":"Use import purgecss from 'rollup-plugin-purgecss'; (ESM) or const { default: purgecss } = require('rollup-plugin-purgecss');","cause":"Using CommonJS require style with default export in ESM-only version.","error":"TypeError: purgecss is not a function"},{"fix":"Replace whitelist with safelist; see migration guide to v3.","cause":"Using deprecated whitelist option from v2.x or earlier.","error":"The 'purgecss' option 'whitelist' is not supported"},{"fix":"Use import purgeCSSPlugin from '@fullhuman/postcss-purgecss';","cause":"Using import { purgeCSSPlugin } from '@fullhuman/postcss-purgecss' in v8.0.0.","error":"Error: PostCSS plugin cannot be imported via named export; use default import."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}