{"id":20485,"library":"purgecss-webpack-plugin","title":"PurgeCSS Webpack Plugin","description":"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.","status":"active","version":"8.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/FullHuman/purgecss","tags":["javascript","webpack-plugin","optimize","optimization","remove","unused","css","html","rules","typescript"],"install":[{"cmd":"npm install purgecss-webpack-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add purgecss-webpack-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add purgecss-webpack-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency – required to run the plugin, must be >=5.0.0","package":"webpack","optional":false},{"reason":"commonly used together; the plugin requires extracted CSS files to purge","package":"mini-css-extract-plugin","optional":true},{"reason":"typically needed to specify file paths for content analysis","package":"glob","optional":true}],"imports":[{"note":"ESM default is not available; named export only. CommonJS require works but destructure from .default? Use named import.","wrong":"const PurgeCSSPlugin = require('purgecss-webpack-plugin')","symbol":"PurgeCSSPlugin","correct":"import { PurgeCSSPlugin } from 'purgecss-webpack-plugin'"},{"note":"TypeScript users can import the type for annotations. No default type export.","symbol":"PurgeCSSPlugin (type)","correct":"import type { PurgeCSSPlugin } from 'purgecss-webpack-plugin'"},{"note":"Although PurgeCSSPlugin conforms to Webpack's plugin interface, its type does not extend WebpackPluginInstance; you may need to cast or use inline types.","symbol":"WebpackPluginInstance (type)","correct":"import { PurgeCSSPlugin } from 'purgecss-webpack-plugin';\nconst plugin: WebpackPluginInstance = new PurgeCSSPlugin({ paths: [] });"}],"quickstart":{"code":"const path = require('path');\nconst glob = require('glob');\nconst MiniCssExtractPlugin = require('mini-css-extract-plugin');\nconst { PurgeCSSPlugin } = require('purgecss-webpack-plugin');\n\nconst PATHS = { src: path.join(__dirname, 'src') };\n\nmodule.exports = {\n  entry: './src/index.js',\n  output: {\n    filename: 'bundle.js',\n    path: path.join(__dirname, 'dist'),\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.css$/,\n        use: [MiniCssExtractPlugin.loader, 'css-loader'],\n      },\n    ],\n  },\n  plugins: [\n    new MiniCssExtractPlugin({ filename: '[name].css' }),\n    new PurgeCSSPlugin({\n      paths: glob.sync(`${PATHS.src}/**/*`, { nodir: true }),\n    }),\n  ],\n};","lang":"javascript","description":"Basic webpack configuration with PurgeCSSPlugin and mini-css-extract-plugin to remove unused CSS."},"warnings":[{"fix":"Use import purgeCSSPlugin from '@fullhuman/postcss-purgecss' instead of named import.","message":"In v8.0.0, the import pattern for the PostCSS plugin changed back to default import.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Provide file paths via the 'paths' option (or a function returning paths).","message":"The plugin does NOT accept 'css' or 'content' options from PurgeCSS; use 'paths' instead.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Replace whitelist with safelist (standard, deep, greedy).","message":"Whitelist option was replaced by safelist in v3.0.0.","severity":"deprecated","affected_versions":">=3.0.0 <3.0.0"},{"fix":"Ensure entry names in 'only' array exactly match output chunk names.","message":"When using the 'only' option, the entry point names must match those generated by webpack's splitChunks – case-sensitive.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use synchronous glob patterns or pre-collect paths outside the webpack config.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade Node.js to >=12 and webpack to >=5.","message":"v5.0.0 dropped support for Node.js < 12 and webpack < 5.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Pass a function to 'paths' that recalculates the file list on each compilation.","message":"The plugin does not automatically track file changes in watch mode unless the 'paths' option is a function or glob patterns are reevaluated.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run: npm install purgecss-webpack-plugin --save-dev","cause":"Package not installed or missing from node_modules.","error":"Error: Cannot find module 'purgecss-webpack-plugin'"},{"fix":"Use const { PurgeCSSPlugin } = require('purgecss-webpack-plugin');","cause":"Using default import instead of named import (CommonJS).","error":"TypeError: PurgeCSSPlugin is not a constructor"},{"fix":"Use 'safelist' instead of deprecated 'whitelist'.","cause":"Incorrect option name (e.g., 'whitelist' instead of 'safelist').","error":"ValidationError: Invalid options object. PurgeCSSPlugin has been initialized using an options object that does not match the API schema."},{"fix":"Check glob pattern; ensure files exist and paths are correct.","cause":"The 'paths' option resolved to an empty array or no matching files.","error":"Error: No files found from the passed PurgeCSS options"},{"fix":"Order plugins: [new MiniCssExtractPlugin(), new PurgeCSSPlugin()]","cause":"PurgeCSS plugin runs before CSS is extracted; ensure MiniCssExtractPlugin is placed before PurgeCSSPlugin in plugins array.","error":"Module build failed (from ./node_modules/mini-css-extract-plugin/dist/loader.js): ModuleParseError: Module parse failed: Unexpected token"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}