[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![cover][cover]][cover-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]
# css-minimizer-webpack-plugin
This plugin uses [cssnano](https://cssnano.co) to optimize and minify your CSS.
Just like [optimize-css-assets-webpack-plugin](https://github.com/NMFR/optimize-css-assets-webpack-plugin) but more accurate with source maps and assets using query string, allows to cache and works in parallel mode.
## Getting Started
To begin, you'll need to install `css-minimizer-webpack-plugin`:
```console
$ npm install css-minimizer-webpack-plugin --save-dev
```
Then add the plugin to your `webpack` configuration. For example:
**webpack.config.js**
```js
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');
module.exports = {
module: {
rules: [
{
test: /.s?css$/,
use: [MiniCssExtractPlugin.loader, 'css-loader', 'sass-loader'],
},
],
},
optimization: {
minimizer: [
// For webpack@5 you can use the `...` syntax to extend existing minimizers (i.e. `terser-webpack-plugin`), uncomment the next line
// `...`,
new CssMinimizerPlugin(),
],
},
};
```
This will enable CSS optimization only in production mode.
If you want to run it also in development set the `optimization.minimize` option to `true`:
**webpack.config.js**
```js
// [...]
module.exports = {
optimization: {
// [...]
minimize: true,
},
};
```
And run `webpack` via your preferred method.
## Note about source maps
**Works only with `source-map`, `inline-source-map`, `hidden-source-map` and `nosources-source-map` values for the [`devtool`](https://webpack.js.org/configuration/devtool/) option.**
Why? Because CSS support only these source map types.
The plugin respect the [`devtool`](https://webpack.js.org/configuration/devtool/) and using the `SourceMapDevToolPlugin` plugin.
Using supported `devtool` values enable source map generation.
Using `SourceMapDevToolPlugin` with enabled the `columns` option enables source map generation.
Use source maps to map error message locations to modules (this slows down the compilation).
If you use your own `minify` function please read the `minify` section for handling source maps correctly.
## Options
### `test`
Type: `String|RegExp|Array` - default: `/\.css(\?.*)?$/i`
Test to match files against.
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new CssMinimizerPlugin({
test: /\.foo\.css$/i,
}),
],
},
};
```
### `include`
Type: `String|RegExp|Array`
Default: `undefined`
Files to include.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new CssMinimizerPlugin({
include: /\/includes/,
}),
],
},
};
```
### `exclude`
Type: `String|RegExp|Array`
Default: `undefined`
Files to exclude.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new CssMinimizerPlugin({
exclude: /\/excludes/,
}),
],
},
};
```
### `parallel`
Type: `Boolean|Number`
Default: `true`
Use multi-process parallel running to improve the build speed.
Default number of concurrent runs: `os.cpus().length - 1`.
> ℹ️ Parallelization can speedup your build significantly and is therefore **highly recommended**.
> If a parallelization is enabled, the packages in `minimizerOptions` must be required via strings (`packageName` or `require.resolve(packageName)`). Read more in [`minimizerOptions`](#minimizerOptions)
#### `Boolean`
Enable/disable multi-process parallel running.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new CssMinimizerPlugin({
parallel: true,
}),
],
},
};
```
#### `Number`
Enable multi-process parallel running and set number of concurrent runs.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new CssMinimizerPlugin({
parallel: 4,
}),
],
},
};
```
### `minify`
Type: `Function|Array`
Default: `CssMinimizerPlugin.cssnanoMinify`
Allows to override default minify function.
By default plugin uses [cssnano](https://github.com/cssnano/cssnano) package.
Useful for using and testing unpublished versions or forks.
Possible options:
- CssMinimizerPlugin.cssnanoMinify
- CssMinimizerPlugin.cssoMinify
- CssMinimizerPlugin.cleanCssMinify
- async (data, inputMap, minimizerOptions) => {return {code: `a{color: red}`, map: `...`, warnings: []}}
> ⚠️ **Always use `require` inside `minify` function when `parallel` option enabled**.
#### `Function`
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new CssMinimizerPlugin({
minimizerOptions: {
level: {
1: {
roundingPrecision: 'all=3,px=5',
},
},
},
minify: CssMinimizerPlugin.cleanCssMinify,
}),
],
},
};
```
#### `Array`
If an array of functions is passed to the `minify` option, the `minimizerOptions` must also be an array.
The function index in the `minify` array corresponds to the options object with the same index in the `minimizerOptions` array.
**webpack.config.js**
```js
module.exports = {
optimization: {
minimize: true,
minimizer: [
new CssMinimizerPlugin({
minimizerOptions: [
{}, // Options for the first function (CssMinimizerPlugin.cssnanoMinify)
{}, // Options for the second function (CssMinimizerPlugin.cleanCssMinify)
{}, // Options for the third function
],
minify: [
CssMinimizerPlugin.cssnanoMinify,
CssMinimizerPlugin.cleanCssMinify,
async (data, inputMap, minimizerOptions) => {
// To do something
return {
code: `a{color: red}`,
map: `{"version": "3", ...}`,
warnings: [],
};
},
],
}),
],
},
};
```
### `minimizerOptions`
Type: `Object|Array
