Registry /
devops / purgecss-webpack-plugin
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PurgeCSSPlugin
✓ import { PurgeCSSPlugin } from 'purgecss-webpack-plugin'
✗ const PurgeCSSPlugin = require('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.
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 }),
}),
],
};
Errors
Common errors & fixes
Error: Cannot find module 'purgecss-webpack-plugin'
Package not installed or missing from node_modules.
fixRun: npm install purgecss-webpack-plugin --save-dev
TypeError: PurgeCSSPlugin is not a constructor
Using default import instead of named import (CommonJS).
fixUse const { PurgeCSSPlugin } = require('purgecss-webpack-plugin'); ValidationError: Invalid options object. PurgeCSSPlugin has been initialized using an options object that does not match the API schema.
Incorrect option name (e.g., 'whitelist' instead of 'safelist').
fixUse 'safelist' instead of deprecated 'whitelist'.
Error: No files found from the passed PurgeCSS options
The 'paths' option resolved to an empty array or no matching files.
fixCheck glob pattern; ensure files exist and paths are correct.
Module build failed (from ./node_modules/mini-css-extract-plugin/dist/loader.js): ModuleParseError: Module parse failed: Unexpected token
PurgeCSS plugin runs before CSS is extracted; ensure MiniCssExtractPlugin is placed before PurgeCSSPlugin in plugins array.
fixOrder plugins: [new MiniCssExtractPlugin(), new PurgeCSSPlugin()]
Audit
Dependencies
webpackrequiredpeer dependency – required to run the plugin, must be >=5.0.0
mini-css-extract-pluginoptionalcommonly used together; the plugin requires extracted CSS files to purge
globoptionaltypically needed to specify file paths for content analysis