Optimize CSS Assets Webpack Plugin

6.0.1 verified Sat Apr 25 auth: no javascript maintenance

A Webpack plugin that searches for CSS assets during the build and optimizes/minimizes them using cssnano by default. It solves the CSS duplication problem when using extract-text-webpack-plugin. The latest version is 6.0.1, but it is deprecated for webpack v5+ in favor of css-minimizer-webpack-plugin. It supports webpack v4 and above, with v4+ requiring webpack v4. Release cadence is low; maintenance mode.

Common errors

error TypeError: OptimizeCssAssetsPlugin is not a constructor ↓

cause Using import statement that returns an object without default export.

fix

Use const OptimizeCssAssetsPlugin = require('optimize-css-assets-webpack-plugin');

error Error: Cannot find module 'cssnano' ↓

cause cssnano is not installed; it is required as a peer or direct dependency.

fix

npm install --save-dev cssnano

error Error: webpack < 4 is not supported ↓

cause Using webpack v3 with v4+ of the plugin.

fix

Use optimize-css-assets-webpack-plugin@3.2.0 for webpack v3.

Warnings

deprecated This plugin is deprecated for webpack v5. Use css-minimizer-webpack-plugin instead. ↓

fix Replace optimize-css-assets-webpack-plugin with css-minimizer-webpack-plugin.

breaking Version 4.0.0 drops support for webpack v3 and below. ↓

fix If using webpack v3, use optimize-css-assets-webpack-plugin@3.2.0.

gotcha The module.exports.CommonJS pattern is required; ES module import may fail. ↓

fix Use require() instead of import.

gotcha The plugin does not support ES module syntax; import will result in undefined. ↓

fix Use const Plugin = require('...')

Install

npm install optimize-css-assets-webpack-plugin

yarn add optimize-css-assets-webpack-plugin

pnpm add optimize-css-assets-webpack-plugin

Imports

OptimizeCssAssetsPlugin

wrong

import OptimizeCssAssetsPlugin from 'optimize-css-assets-webpack-plugin';

correct

const OptimizeCssAssetsPlugin = require('optimize-css-assets-webpack-plugin');

CommonJS require is the recommended pattern; ESM import may fail if the package does not provide an ESM entry.

OptimizeCssAssetsPlugin

wrong

const { OptimizeCssAssetsPlugin } = require('optimize-css-assets-webpack-plugin');

correct

const OptimizeCssAssetsPlugin = require('optimize-css-assets-webpack-plugin');

The package exports a single constructor function, not a named export. Destructuring will result in undefined.

OptimizeCssAssetsPlugin

wrong

const Opt = require('optimize-css-assets-webpack-plugin').default;

correct

const OptimizeCssAssetsPlugin = require('optimize-css-assets-webpack-plugin');

CommonJS module does not have a default export; accessing .default yields undefined.

Quickstart

Configures webpack v4 with extract-text-webpack-plugin and optimize-css-assets-webpack-plugin to extract CSS into a separate file and minimize it using cssnano.

const path = require('path');
const webpack = require('webpack');
const ExtractTextPlugin = require('extract-text-webpack-plugin');
const OptimizeCssAssetsPlugin = require('optimize-css-assets-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ExtractTextPlugin.extract({
          fallback: 'style-loader',
          use: 'css-loader'
        })
      }
    ]
  },
  plugins: [
    new ExtractTextPlugin('styles.css'),
    new OptimizeCssAssetsPlugin({
      assetNameRegExp: /\.optimize\.css$/g,
      cssProcessor: require('cssnano'),
      cssProcessorPluginOptions: {
        preset: ['default', { discardComments: { removeAll: true } }]
      },
      canPrint: true
    })
  ]
};