postcss-assets-webpack-plugin

4.1.2 verified Sat Apr 25 auth: no javascript

A Webpack plugin that applies PostCSS transformations to CSS assets emitted by MiniCssExtractPlugin after all files are compiled. Version 4.1.2 supports Webpack 4 and 5 with PostCSS 8, requiring Node >=10. Unlike postcss-loader which processes files individually, this plugin enables whole-bundle optimizations like media query packing and minimization. It is stable with infrequent releases and no known security issues.

Common errors

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

cause MiniCssExtractPlugin not used or not yet emitted assets when plugin runs.

fix

Ensure MiniCssExtractPlugin is registered before PostCSSAssetsPlugin in the plugins array.

error Error: PostCSS plugin returned undefined. Did you forget to return a function? ↓

cause Plugin in the `plugins` array is not a valid PostCSS plugin (e.g., a string or invalid object).

fix

Check that all items in the plugins array are PostCSS plugin instances (e.g., require('mqpacker')() ).

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

cause PostCSS is not installed as a dependency.

fix

Run npm install --save-dev postcss.

Warnings

breaking PostCSSAssetsPlugin 4.x removed support for PostCSS plugins used via string names. All plugins must be passed as PostCSS plugin functions (objects). ↓

fix Ensure each plugin in the `plugins` array is a PostCSS plugin object, not a string package name.

breaking Version 4.0.0 requires Node >=10 and Webpack >=4. Older versions are incompatible. ↓

fix Upgrade to v4+ or use an older version of the plugin with compatible Node and Webpack.

deprecated The `test` option is required but the plugin will log a warning if no files match. It is not deprecated but usage is mandatory. ↓

fix Always provide a `test` regex that matches your CSS filenames to avoid processing failures.

gotcha The plugin only processes assets emitted by MiniCssExtractPlugin. Other CSS assets (e.g., from style-loader) are ignored. ↓

fix Ensure you use MiniCssExtractPlugin in production and that CSS files are extracted before the emit hook.

Install

npm install postcss-assets-webpack-plugin

yarn add postcss-assets-webpack-plugin

pnpm add postcss-assets-webpack-plugin

Imports

PostCSSAssetsPlugin

wrong

const PostCSSAssetsPlugin = require('postcss-assets-webpack-plugin')

correct

import PostCSSAssetsPlugin from 'postcss-assets-webpack-plugin'

Package is ESM-only; using require will fail. Use import or dynamic import.

PostCSSAssetsPlugin

wrong

import type { PostCSSAssetsPlugin } from 'postcss-assets-webpack-plugin'

correct

// No type import; plugin is not typed
// Use @types/postcss-assets-webpack-plugin if available

The package does not ship TypeScript declarations; community types may exist.

PostCSSAssetsPlugin

wrong

const PostCSSAssetsPlugin = require('postcss-assets-webpack-plugin')

correct

const PostCSSAssetsPlugin = require('postcss-assets-webpack-plugin').default

In CommonJS, the default export is under .default; direct require returns a module object.

Quickstart

Configures Webpack to extract CSS with MiniCssExtractPlugin and then apply PostCSS plugins (mqpacker and csswring) to the bundled CSS using postcss-assets-webpack-plugin.

import webpack from 'webpack';
import csswring from 'csswring';
import mqpacker from 'mqpacker';
import autoprefixer from 'autoprefixer';
import MiniCssExtractPlugin from 'mini-css-extract-plugin';
import PostCSSAssetsPlugin from 'postcss-assets-webpack-plugin';

const devMode = process.env.NODE_ENV !== 'production';

export default {
  entry: './src/index.js',
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          devMode ? 'style-loader' : MiniCssExtractPlugin.loader,
          'css-loader',
          'postcss-loader'
        ]
      }
    ]
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: devMode ? '[name].css' : '[name].[contenthash].css'
    }),
    new PostCSSAssetsPlugin({
      test: /\.css$/,
      plugins: [
        mqpacker(),
        csswring({ preservehacks: true, removeallcomments: true })
      ],
      log: !devMode
    })
  ]
}