Webpack

Tips

You can use either the Webpack plugin directly in your webpack configuration or use the PostCSS plugin when you are using the Webpack postCSS loader.

Installation

npm i purgecss-webpack-plugin -D

Usage

With mini-css-extract-plugin

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"),
  },
  optimization: {
    splitChunks: {
      cacheGroups: {
        styles: {
          name: "styles",
          test: /\.css$/,
          chunks: "all",
          enforce: true,
        },
      },
    },
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: "[name].css",
    }),
    new PurgeCSSPlugin({
      paths: glob.sync(`${PATHS.src}/**/*`, { nodir: true }),
    }),
  ],
};

Multiple paths

If you need multiple paths use the npm package glob-all instead of glob, then you can use this syntax:

new PurgeCSSPlugin({
  paths: glob.sync([
    // ...
  ])
}),

to filter out directories see the glob-all documentation here.

Options

The webpack plugin passes the following options of the purgecss Configuration to PurgeCSS: defaultExtractor, extractors, fontFace, keyframes, variables, safelist, blocklist, dynamicAttributes and rejected. The plugin purges the CSS assets of the compilation and uses paths as the content, so it doesn't take the css and content options. Source maps are generated when the webpack devtool option is set. Other options, such as rejectedCss or skippedContentGlobs, have no effect.

With the webpack plugin, you can specify the content that should be analyzed by purgecss by providing an array of filenames. These can be html, pug, blade, ... files. You can also use a module like glob or glob-all to easily get a list of files.

You likely need to pass { nodir: true } as an option to glob.sync() as glob.sync is matching a dir which the plugin can't operate on.

const { PurgeCSSPlugin } = require("purgecss-webpack-plugin");
const glob = require("glob");
const PATHS = {
  src: path.join(__dirname, "src"),
};

// In the webpack configuration
new PurgeCSSPlugin({
  paths: glob.sync(`${PATHS.src}/**/*`, { nodir: true }),
});

If you want to regenerate the list of paths on every compilation (e.g. when using --watch), then you can also pass a function to the paths option as in the following example:

new PurgeCSSPlugin({
  paths: () => glob.sync(`${PATHS.src}/**/*`, { nodir: true }),
});

You can specify chunk names to the purgecss-webpack-plugin with the option only:

new PurgeCSSPlugin({
  paths: glob.sync(`${PATHS.src}/**/*`, { nodir: true }),
  only: ["bundle", "vendor"],
});

The names are compared with the chunk names (for an entrypoint, its key in entry), not with the file names.

Similar as for the paths option, you also can define a function for this option:

function collectSafelist() {
  return {
    standard: ["safelisted", /^safelisted-/],
    deep: [/^safelisted-deep-/],
    greedy: [/^safelisted-greedy/],
  };
}

// In the webpack configuration
new PurgeCSSPlugin({
  safelist: collectSafelist,
});

When this option is set to true all removed selectors are added to the Stats Data as purged.