postcss-pipeline-webpack-plugin

6.0.0 verified Sat Apr 25 auth: no javascript

Webpack 5 plugin that processes generated CSS assets with PostCSS pipelines, enabling multi-file transformations like critical CSS extraction and minification where loaders fall short. Version 6.0.0 (latest) requires Node >=10 and webpack ^5; for webpack 4 use v5, for webpack 3 use v3. Key differentiator: processes all generated CSS files (including those from plugins like MiniCssExtractPlugin) through PostCSS plugins in a pipeline, with support for custom filters, naming (prefix, suffix, transformName), and source maps. Supports PostCSS 6, 7, 8.0.

Common errors

error TypeError: Cannot read property 'compilation' of undefined ↓

cause Plugin instance not instantiated before adding to plugins array.

fix

Ensure you use 'new PostCssPipelineWebpackPlugin({...})' and not the class itself.

error Module not found: Error: Can't resolve 'postcss' ↓

cause postcss is not installed as a dependency; it's a peer dependency.

fix

Run 'npm install postcss --save-dev' to install PostCSS.

error TypeError: Cannot read property 'CriticalCss' of undefined ↓

cause Attempting to use postcss-critical-split without proper import.

fix

Import the plugin: const criticalSplit = require('postcss-critical-split');

Warnings

breaking v3.0.0 requires Node.js >=4.7; older Node versions are incompatible. ↓

fix Upgrade Node.js to >=4.7 or use postcss-pipeline-webpack-plugin@1.x.

breaking Plugin requires webpack 5 for v6; v5 uses webpack 4, v3 uses webpack 3. ↓

fix Use postcss-pipeline-webpack-plugin@5 for webpack 4, or @3 for webpack 3.

gotcha PostCSS instance must be passed via 'processor' option; the plugin does not create one automatically. ↓

fix const postcss = require('postcss'); new PostCssPipelineWebpackPlugin({ processor: postcss([plugin]) });

gotcha Source map options under 'map' property are passed directly to PostCSS; ensure compatibility with your PostCSS version. ↓

fix Consult PostCSS source map documentation for appropriate options.

Install

npm install postcss-pipeline-webpack-plugin

yarn add postcss-pipeline-webpack-plugin

pnpm add postcss-pipeline-webpack-plugin

Imports

PostCssPipelineWebpackPlugin

wrong

import PostCssPipelineWebpackPlugin from 'postcss-pipeline-webpack-plugin';

correct

const PostCssPipelineWebpackPlugin = require('postcss-pipeline-webpack-plugin');

The package is CJS-only; no default ESM export. Use require().

new PostCssPipelineWebpackPlugin({...})

wrong

new PostCssPipelineWebpackPlugin();

correct

const pipelinePlugin = new PostCssPipelineWebpackPlugin({ processor: postcss([...]) });

The constructor requires at least a 'processor' option (a PostCSS instance).

plugin instance usage

wrong

module.exports.plugins = [PostCssPipelineWebpackPlugin];

correct

plugins: [new PostCssPipelineWebpackPlugin({...})]

You must instantiate the plugin before adding to webpack plugins array.

Quickstart

Sets up PostCSS pipeline to minify all extracted CSS files using csso, adding a '.min' suffix and generating source maps.

const path = require('path');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const PostCssPipelineWebpackPlugin = require('postcss-pipeline-webpack-plugin');
const postcss = require('postcss');
const csso = require('postcss-csso');

module.exports = {
  mode: 'production',
  entry: './src/index.css',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          MiniCssExtractPlugin.loader,
          'css-loader',
        ],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: 'styles.css',
    }),
    new PostCssPipelineWebpackPlugin({
      suffix: 'min',
      processor: postcss([
        csso()
      ]),
      map: { inline: false },
    }),
  ],
};