Skip to content

docs: fix typos and improve clarity in README.md #284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 30, 2025
Merged

docs: fix typos and improve clarity in README.md #284

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 50 additions & 49 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

This plugin uses [cssnano](https://cssnano.github.io/cssnano/) 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 caching and works in parallel mode.
It serves as a more accurate alternative to [optimize-css-assets-webpack-plugin](https://github.com/NMFR/optimize-css-assets-webpack-plugin), with better support for source maps, assets with query strings, caching, and parallel processing.

## Getting Started

Expand Down Expand Up @@ -49,25 +49,26 @@ module.exports = {
module: {
rules: [
{
test: /.s?css$/,
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
// `...`,
// For webpack v5, you can use the `...` syntax to extend existing minimizers (i.e. `terser-webpack-plugin`), uncomment the next line // `...`,
new CssMinimizerPlugin(),
],
},
plugins: [new MiniCssExtractPlugin()],
};
```

This will enable CSS optimization only in production mode.
> [!NOTE]
>
> This enables CSS optimization only in production mode by default.

If you want to run it also in development set the `optimization.minimize` option to `true`:
To enable it in development mode as well, set the `optimization.minimize` option to `true`:

**webpack.config.js**

Expand All @@ -81,20 +82,20 @@ module.exports = {
};
```

And run `webpack` via your preferred method.
Finally, run Webpack using 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.**
**This plugin 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.
The plugin respects the [`devtool`](https://webpack.js.org/configuration/devtool/) setting and uses the `SourceMapDevToolPlugin` internally.
Using a supported `devtool` value enables source map generation.
Enabling the `columns` option in `SourceMapDevToolPlugin` also allows 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.
Use source maps to map error message locations to their original modules (note that this may slow down compilation).
If you use your own `minify` function please refer to the `minify` section for correct handling of source maps.

## Options

Expand All @@ -103,14 +104,15 @@ If you use your own `minify` function please read the `minify` section for handl
| **[`test`](#test)** | `String\|RegExp\|Array<String\|RegExp>` | `/\.css(\?.*)?$/i` | Test to match files against. |
| **[`include`](#include)** | `String\|RegExp\|Array<String\|RegExp>` | `undefined` | Files to include. |
| **[`exclude`](#exclude)** | `String\|RegExp\|Array<String\|RegExp>` | `undefined` | Files to exclude. |
| **[`parallel`](#parallel)** | `Boolean\|Number` | `true` | Enable/disable multi-process parallel running. |
| **[`parallel`](#parallel)** | `Boolean\|Number` | `true` | Enable or disable multi-process parallel running. |
| **[`minify`](#minify)** | `Function\|Array<Function>` | `CssMinimizerPlugin.cssnanoMinify` | Allows to override default minify function. |
| **[`minimizerOptions`](#minimizeroptions)** | `Object\|Array<Object>` | `{ preset: 'default' }` | Cssnano optimisations [options](https://cssnano.github.io/cssnano/docs/what-are-optimisations/). |
| **[`warningsFilter`](#warningsfilter)** | `Function<(warning, file, source) -> Boolean>` | `() => true` | Allow to filter css-minimizer warnings. |
| **[`warningsFilter`](#warningsfilter)** | `Function<(warning, file, source) -> Boolean>` | `() => true` | Allows filtering of css-minimizer warnings. |

### `test`

Type: `String|RegExp|Array<String|RegExp>` - default: `/\.css(\?.*)?$/i`
- Type: `String|RegExp|Array<String|RegExp>`
- Default: `/\.css(\?.*)?$/i`

Test to match files against.

Expand All @@ -129,8 +131,8 @@ module.exports = {

### `include`

Type: `String|RegExp|Array<String|RegExp>`
Default: `undefined`
- Type: `String|RegExp|Array<String|RegExp>`
- Default: `undefined`

Files to include.

Expand All @@ -151,8 +153,8 @@ module.exports = {

### `exclude`

Type: `String|RegExp|Array<String|RegExp>`
Default: `undefined`
- Type: `String|RegExp|Array<String|RegExp>`
- Default: `undefined`

Files to exclude.

Expand All @@ -173,18 +175,18 @@ module.exports = {

### `parallel`

Type: `Boolean|Number`
Default: `true`
- Type: `Boolean|Number`
- Default: `true`

Use multi-process parallel running to improve the build speed.
Default number of concurrent runs: `os.cpus().length - 1` or `os.availableParallelism() - 1` (if this function is supported).
The default number of concurrent runs: `os.cpus().length - 1` or `os.availableParallelism() - 1` (if this function is supported).

> ℹ️ Parallelization can speed up 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.
Enable or disable multi-process parallel running.

**webpack.config.js**

Expand All @@ -203,7 +205,7 @@ module.exports = {

#### `Number`

Enable multi-process parallel running and set number of concurrent runs.
Enable multi-process parallel running and specify the number of concurrent runs.

**webpack.config.js**

Expand All @@ -222,12 +224,12 @@ module.exports = {

### `minify`

Type: `Function|Array<Function>`
Default: `CssMinimizerPlugin.cssnanoMinify`
- Type: `Function|Array<Function>`
- Default: `CssMinimizerPlugin.cssnanoMinify`

Allows overriding default minify function.
Overrides the default minify function.
By default, plugin uses [cssnano](https://github.com/cssnano/cssnano) package.
Useful for using and testing unpublished versions or forks.
This is useful when using or testing unpublished versions or forks.

Possible options:

Expand All @@ -240,7 +242,7 @@ Possible options:

> [!WARNING]
>
> **Always use `require` inside `minify` function when `parallel` option enabled**.
> **Always use `require` inside `minify` function when `parallel` option is enabled**.

#### `Function`

Expand Down Expand Up @@ -288,7 +290,7 @@ module.exports = {
CssMinimizerPlugin.cssnanoMinify,
CssMinimizerPlugin.cleanCssMinify,
async (data, inputMap, minimizerOptions) => {
// To do something
// Custom minifier function
return {
code: `a{color: red}`,
map: `{"version": "3", ...}`,
Expand All @@ -305,8 +307,8 @@ module.exports = {

### `minimizerOptions`

Type: `Object|Array<Object>`
Default: `{ preset: 'default' }`
- Type: `Object|Array<Object>`
- Default: `{ preset: 'default' }`

Cssnano optimisations [options](https://cssnano.co/docs/what-are-optimisations/).

Expand Down Expand Up @@ -337,7 +339,7 @@ module.exports = {
The function index in the `minify` array corresponds to the options object with the same index in the `minimizerOptions` array.
If you use `minimizerOptions` like object, all `minify` function accept it.

> If a parallelization is enabled, the packages in `minimizerOptions` must be required via strings (`packageName` or `require.resolve(packageName)`). In this case, we shouldn't use `require`/`import`.
> If parallelization is enabled, the packages in `minimizerOptions` must be referenced via strings (`packageName` or `require.resolve(packageName)`). In this case, we shouldn't use `require`/`import`.

```js
module.exports = {
Expand All @@ -356,15 +358,15 @@ module.exports = {

##### `processorOptions` (⚠ only cssnano)

Type: `Object`
Default: `{ from: assetName }`
- Type: `Object`
- Default: `{ from: assetName }`

Allows filtering options [`processoptions`](https://postcss.org/api/#processoptions) for the cssnano.
The `parser`,` stringifier` and `syntax` can be either a function or a string indicating the module that will be imported.

> [!WARNING]
>
> **If a function is passed, the `parallel` option must be disabled.**.
> **If any of these options are passed as a function, the `parallel` option must be disabled.**.

```js
import sugarss from "sugarss";
Expand Down Expand Up @@ -405,15 +407,15 @@ module.exports = {

### `warningsFilter`

Type: `Function<(warning, file, source) -> Boolean>`
Default: `() => true`
- Type: `Function<(warning, file, source) -> Boolean>`
- Default: `() => true`

Allow filtering css-minimizer warnings (By default [cssnano](https://github.com/cssnano/cssnano)).
Return `true` to keep the warning, a falsy value (`false`/`null`/`undefined`) otherwise.
Filter css-minimizer warnings (By default [cssnano](https://github.com/cssnano/cssnano)).
Return `true` to keep the warning, or a falsy value (`false`/`null`/`undefined`) to suppress it.

> [!WARNING]
>
> The `source` argument will contain `undefined` if you don't use source maps.
> The `source` parameter will be `undefined` unless source maps are enabled.

**webpack.config.js**

Expand Down Expand Up @@ -458,7 +460,7 @@ module.exports = {
module: {
rules: [
{
test: /.s?css$/,
test: /\.s?css$/,
use: [
MiniCssExtractPlugin.loader,
{ loader: "css-loader", options: { sourceMap: true } },
Expand All @@ -476,7 +478,7 @@ module.exports = {

### Remove all comments

Remove all comments (including comments starting with `/*!`).
Remove all comments, including those starting with `/*!`.

```js
module.exports = {
Expand Down Expand Up @@ -564,8 +566,7 @@ module.exports = {

```js
module.exports = {
// Uncomment if you need source maps
// devtool: "source-map",
// devtool: "source-map", // Uncomment for source maps
optimization: {
minimize: true,
minimizer: [
Expand All @@ -585,8 +586,7 @@ module.exports = {

```js
module.exports = {
// Uncomment if you need source maps
// devtool: "source-map",
// devtool: "source-map", // Uncomment for source maps
optimization: {
minimize: true,
minimizer: [
Expand All @@ -602,7 +602,8 @@ module.exports = {

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.
We welcome all contributions!
If you're new here, please take a moment to review our contributing guidelines.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

Expand Down