Extract CSS Chunks Webpack Plugin

4.10.0 verified Sat Apr 25 auth: no javascript maintenance

A webpack plugin that extracts CSS from chunks into separate stylesheets with Hot Module Replacement (HMR) support. Current stable version is 4.10.0 (last released November 2020). It is a fork/enhancement of mini-css-extract-plugin, adding HMR and SSR compatibility. Supports Webpack 4 and 5, ships TypeScript declarations, and is designed for code-splitting applications. Key differentiator: built-in HMR for extracted CSS files without additional loaders, and chunk-based CSS extraction for universal (SSR) apps. Active maintenance status as of 2020, but no recent releases.

Common errors

error Module not found: Can't resolve 'extract-css-chunks-webpack-plugin' ↓

cause Package not installed or missing from node_modules.

fix

Run npm install extract-css-chunks-webpack-plugin --save-dev or yarn add extract-css-chunks-webpack-plugin --dev.

error Error: Chunk.entryModule was removed; use ChunkGraph ↓

cause Using an older version of the plugin with Webpack 5.

fix

Upgrade extract-css-chunks-webpack-plugin to v4.10.0 or later, which supports Webpack 5.

error Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema. ↓

cause Incorrect plugin options, e.g., misspelled 'filename' or 'chunkFilename'.

fix

Check plugin options: use 'filename' and 'chunkFilename' strings (not functions).

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

cause Loader not applied correctly; missing ExtractCssChunks.loader in webpack config.

fix

Ensure rules for .css files include ExtractCssChunks.loader before css-loader.

Warnings

gotcha HMR only works in development mode. Do not enable HMR in production. ↓

fix Set options.hmr to false or omit it in production, or use webpack mode differentiation.

gotcha Must set output.publicPath to a non-empty value for CSS chunks to resolve correctly in some cases. ↓

fix Set output.publicPath to '/' or your CDN URL.

deprecated The plugin is based on mini-css-extract-plugin; consider migrating if you don't need HMR. ↓

fix Replace with mini-css-extract-plugin if HMR not required.

gotcha Async CSS chunks may not apply correctly in Webpack 5 without proper configuration. ↓

fix Ensure you are using a compatible version; test with Webpack 5 explicitly.

gotcha The insert option (for custom placement of style tags) may cause render blocking in Safari if misconfigured. ↓

fix Upgrade to v4.8.0+ which fixes Safari render blocking.

Install

npm install extract-css-chunks-webpack-plugin

yarn add extract-css-chunks-webpack-plugin

pnpm add extract-css-chunks-webpack-plugin

Imports

default (ExtractCssChunks)
wrong
```
import ExtractCssChunks from 'extract-css-chunks-webpack-plugin';
```
correct
```
const ExtractCssChunks = require('extract-css-chunks-webpack-plugin');
```
CommonJS default export is the correct pattern; ESM default import may fail in some bundler versions. TypeScript users should also use require or set esModuleInterop.
loader
wrong
```
require('extract-css-chunks-webpack-plugin/dist/loader')
```
correct
```
ExtractCssChunks.loader
```
The loader is accessed as a static property on the plugin instance, not via subpath.
Types
```
const ExtractCssChunks = require('extract-css-chunks-webpack-plugin');
```
TypeScript types are included and automatically resolved when importing the package. No separate type import needed.

Quickstart

Basic webpack config showing usage of ExtractCssChunks plugin with its loader, including HMR option and CSS extraction in production.

// webpack.config.js
const path = require('path');
const ExtractCssChunks = require('extract-css-chunks-webpack-plugin');

module.exports = {
  mode: 'production',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
    publicPath: '/',
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: ExtractCssChunks.loader,
            options: {
              // Enable HMR in development
              hmr: process.env.NODE_ENV === 'development',
            },
          },
          'css-loader',
        ],
      },
    ],
  },
  plugins: [
    new ExtractCssChunks({
      filename: '[name].[contenthash].css',
      chunkFilename: '[id].[contenthash].css',
    }),
  ],
};