PurgeCSS Webpack Plugin

8.0.0 verified Sat Apr 25 auth: no javascript

Webpack plugin to remove unused CSS using PurgeCSS. Version 8.0.0 (released 2025) is current stable; requires webpack 5 and ships TypeScript definitions. Key differentiators: supports mini-css-extract-plugin, dynamic paths via function for watch mode, safelist/blocklist options, and 'only' option to limit processing to specific entry points. Compatible with PurgeCSS configuration but excludes 'css' and 'content' options. Breaking changes in v8.0.0: reverted import pattern for PostCSS plugin back to default import. Release cadence: major versions every 1-2 years.

Common errors

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

cause Package not installed or missing from node_modules.

fix

Run: npm install purgecss-webpack-plugin --save-dev

error TypeError: PurgeCSSPlugin is not a constructor ↓

cause Using default import instead of named import (CommonJS).

fix

Use const { PurgeCSSPlugin } = require('purgecss-webpack-plugin');

error ValidationError: Invalid options object. PurgeCSSPlugin has been initialized using an options object that does not match the API schema. ↓

cause Incorrect option name (e.g., 'whitelist' instead of 'safelist').

fix

Use 'safelist' instead of deprecated 'whitelist'.

error Error: No files found from the passed PurgeCSS options ↓

cause The 'paths' option resolved to an empty array or no matching files.

fix

Check glob pattern; ensure files exist and paths are correct.

error Module build failed (from ./node_modules/mini-css-extract-plugin/dist/loader.js): ModuleParseError: Module parse failed: Unexpected token ↓

cause PurgeCSS plugin runs before CSS is extracted; ensure MiniCssExtractPlugin is placed before PurgeCSSPlugin in plugins array.

fix

Order plugins: [new MiniCssExtractPlugin(), new PurgeCSSPlugin()]

Warnings

breaking In v8.0.0, the import pattern for the PostCSS plugin changed back to default import. ↓

fix Use import purgeCSSPlugin from '@fullhuman/postcss-purgecss' instead of named import.

gotcha The plugin does NOT accept 'css' or 'content' options from PurgeCSS; use 'paths' instead. ↓

fix Provide file paths via the 'paths' option (or a function returning paths).

deprecated Whitelist option was replaced by safelist in v3.0.0. ↓

fix Replace whitelist with safelist (standard, deep, greedy).

gotcha When using the 'only' option, the entry point names must match those generated by webpack's splitChunks – case-sensitive. ↓

fix Ensure entry names in 'only' array exactly match output chunk names.

gotcha If paths are provided as a function, it must return an array of strings and is called on each compilation; avoid asynchronous generation inside the function. ↓

fix Use synchronous glob patterns or pre-collect paths outside the webpack config.

breaking v5.0.0 dropped support for Node.js < 12 and webpack < 5. ↓

fix Upgrade Node.js to >=12 and webpack to >=5.

gotcha The plugin does not automatically track file changes in watch mode unless the 'paths' option is a function or glob patterns are reevaluated. ↓

fix Pass a function to 'paths' that recalculates the file list on each compilation.

Install

npm install purgecss-webpack-plugin

yarn add purgecss-webpack-plugin

pnpm add purgecss-webpack-plugin

Imports

PurgeCSSPlugin
wrong
```
const PurgeCSSPlugin = require('purgecss-webpack-plugin')
```
correct
```
import { PurgeCSSPlugin } from 'purgecss-webpack-plugin'
```
ESM default is not available; named export only. CommonJS require works but destructure from .default? Use named import.
PurgeCSSPlugin (type)
```
import type { PurgeCSSPlugin } from 'purgecss-webpack-plugin'
```
TypeScript users can import the type for annotations. No default type export.
WebpackPluginInstance (type)
```
import { PurgeCSSPlugin } from 'purgecss-webpack-plugin';
const plugin: WebpackPluginInstance = new PurgeCSSPlugin({ paths: [] });
```
Although PurgeCSSPlugin conforms to Webpack's plugin interface, its type does not extend WebpackPluginInstance; you may need to cast or use inline types.

Quickstart

Basic webpack configuration with PurgeCSSPlugin and mini-css-extract-plugin to remove unused CSS.

const path = require('path');
const glob = require('glob');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const { PurgeCSSPlugin } = require('purgecss-webpack-plugin');

const PATHS = { src: path.join(__dirname, 'src') };

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.join(__dirname, 'dist'),
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, 'css-loader'],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({ filename: '[name].css' }),
    new PurgeCSSPlugin({
      paths: glob.sync(`${PATHS.src}/**/*`, { nodir: true }),
    }),
  ],
};