clean-css-loader

4.2.1 verified Sat Apr 25 auth: no javascript

A webpack loader that minifies CSS using CleanCSS. Current stable version is 4.2.1 (released February 2023), with maintenance-level updates. It supports webpack 2+ and works with schema-utils v3/v4, loader-utils v1-v3. Key differentiators: minimal configuration, supports CleanCSS level 2 optimizations, source maps, and inline import options. Competing loaders like css-minimizer-webpack-plugin are more modern but this loader is simpler for basic minification. Ships TypeScript types.

Common errors

error Error: CleanCSSLoader is not a constructor ↓

cause Using import statement on the loader directly in application code instead of webpack config

fix

Do not import 'clean-css-loader' in application JS; only reference it as a string or object in webpack config.

error Module not found: Error: Can't resolve 'clean-css-loader' in /path ↓

cause Package not installed or webpack config missing resolveLoader

fix

Run 'npm install --save-dev clean-css-loader' and ensure node_modules is accessible.

error TypeError: this.getOptions is not a function ↓

cause Using an incompatible version of webpack or loader-utils

fix

Upgrade webpack to >=5 and loader-utils to >=3, or downgrade clean-css-loader to 4.1.x.

Warnings

breaking webpack 5 changes how query string options are parsed: `?skipWarn=true` becomes string 'true' instead of boolean true ↓

fix Use an options object in webpack config instead of inline query strings.

deprecated Node.js 12 support dropped in v4.2.0 ↓

fix Upgrade to Node.js >=14.

gotcha Loader-utils v3 changed option parsing; boolean values in query strings are not coerced ↓

fix Use options object or upgrade loader-utils to v3 and pass primitive values correctly.

gotcha When using with css-minimizer-webpack-plugin, do not use clean-css-loader in minimization step; use one or the other ↓

fix Remove clean-css-loader if using css-minimizer-webpack-plugin, or configure plugin to use clean-css instead.

Install

npm install clean-css-loader

yarn add clean-css-loader

pnpm add clean-css-loader

Imports

default
wrong
```
import cleanCssLoader from 'clean-css-loader'
```
correct
```
module.exports = { loader: 'clean-css-loader', options: { ... } }
```
This is a webpack loader, not a module to import in code. Use it in webpack config as a string or object.
inline import
wrong
```
import 'clean-css-loader!./style.css'
```
correct
```
import 'style-loader!css-loader!clean-css-loader!./style.css'
```
Inline import must chain with style-loader and css-loader; omitting them will not produce CSS in the bundle.
webpack rules
wrong
```
use: ['style-loader', 'css-loader', { loader: 'clean-css-loader?level=2' }]
```
correct
```
use: ['style-loader', 'css-loader', 'clean-css-loader']
```
Use options object instead of query string (e.g. `?level=2`) because webpack 5 parses query strings differently; strings like 'true' are not coerced to boolean.

Quickstart

Shows webpack config with clean-css-loader, including conditional disable for dev and CleanCSS level 2 optimization.

// webpack.config.js
const isProduction = process.env.NODE_ENV === 'production';

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'clean-css-loader',
            options: {
              disable: !isProduction,
              skipWarn: false,
              sourceMap: true,
              level: 2,
              compatibility: 'ie9',
            },
          },
        ],
      },
    ],
  },
};