csso-loader

0.3.1 verified Sat Apr 25 auth: no javascript maintenance

Webpack loader for CSS minification using CSSO. Current stable version is 0.3.1, with basic support for CSSO's restructure, comments, debug, and usage options. This loader allows inline query parameters or a top-level 'csso' config object. It works with webpack 1.x (loaders array) and has limited updates since last release; modern webpack versions may require a different loader syntax. It integrates after css-loader to minify CSS output.

Common errors

error Module build failed: Error: No handler for content type 'text/css' ↓

cause csso-loader receives non-CSS content, e.g., from css-loader output with modules enabled.

fix

Disable CSS modules for the rule targeted by csso-loader, or use a different minifier.

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

cause Using webpack 2+ and placing options in 'csso' object without LoaderOptionsPlugin.

fix

Wrap csso options in new webpack.LoaderOptionsPlugin({ options: { csso: { restructure: false } } }) and apply to the correct loaders.

error Error: Cannot find module 'csso' ↓

cause csso not installed or not in node_modules.

fix

Install csso as a devDependency: npm install csso --save-dev

Warnings

deprecated This package uses webpack 1.x loader syntax. webpack 2+ uses rules.use or LoaderOptionsPlugin. ↓

fix For webpack 2+, replace 'loaders' with 'rules' and use 'loaderOptionsPlugin' to pass options or switch to style-loader / css-loader built-in minification.

gotcha Options in webpack config must be placed in top-level 'csso' object, not inside loader options. ↓

fix Either use query parameters in the loader string, or add 'csso' as a top-level key in webpack config.

gotcha Loader chain order: css-loader must come before csso-loader (rightmost in loader string). ↓

fix Always use 'css-loader!csso-loader' in loader string so csso-loader receives already-parsed CSS.

breaking CSSo 4.0+ dropped some options, but csso-loader pins to older csso version. ↓

fix Pin csso version to 3.x or migrate to a modern minifier like css-minimizer-webpack-plugin.

Install

npm install csso-loader

yarn add csso-loader

pnpm add csso-loader

Imports

default
wrong
```
import { csso-loader } from 'csso-loader'
```
correct
```
module.exports = { module: { loaders: [ { test: /\.css$/, loader: 'css-loader!csso-loader' } ] } }
```
The loader is used via webpack configuration, not imported directly in code. It must be chained after css-loader to minify CSS output.
csso
wrong
```
import csso from 'csso-loader'
```
correct
```
new webpack.LoaderOptionsPlugin({ options: { csso: { restructure: false } } })
```
Options are passed via the 'csso' object in webpack config, not by importing the loader directly. Use LoaderOptionsPlugin for webpack 2+.
query parameters
wrong
```
loader: 'csso-loader?restructure=false'
```
correct
```
loader: 'css-loader!csso-loader?-restructure&comments=false'
```
Query parameters use a minus sign to disable default options (e.g., -restructure). Boolean false requires the '?' prefix for disabled features.

Quickstart

Minimal webpack config using csso-loader after css-loader to minify CSS files.

// webpack.config.js
module.exports = {
  entry: './index.js',
  output: { filename: 'bundle.js' },
  module: {
    loaders: [
      {
        test: /\.css$/,
        loader: 'css-loader!csso-loader',
      }
    ]
  }
};