From 54f544b8a331fa4f1ca681f28efe9e9a02939151 Mon Sep 17 00:00:00 2001 From: Sachin Kumar Date: Fri, 30 May 2025 17:54:21 +0530 Subject: [PATCH] docs: fix typos and improve clarity in README.md (#284) --- README.md | 99 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 50 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 793fa31..b41a858 100644 --- a/README.md +++ b/README.md @@ -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 @@ -49,15 +49,14 @@ 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(), ], }, @@ -65,9 +64,11 @@ module.exports = { }; ``` -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** @@ -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 @@ -103,14 +104,15 @@ If you use your own `minify` function please read the `minify` section for handl | **[`test`](#test)** | `String\|RegExp\|Array` | `/\.css(\?.*)?$/i` | Test to match files against. | | **[`include`](#include)** | `String\|RegExp\|Array` | `undefined` | Files to include. | | **[`exclude`](#exclude)** | `String\|RegExp\|Array` | `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` | `CssMinimizerPlugin.cssnanoMinify` | Allows to override default minify function. | | **[`minimizerOptions`](#minimizeroptions)** | `Object\|Array` | `{ 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` - default: `/\.css(\?.*)?$/i` +- Type: `String|RegExp|Array` +- Default: `/\.css(\?.*)?$/i` Test to match files against. @@ -129,8 +131,8 @@ module.exports = { ### `include` -Type: `String|RegExp|Array` -Default: `undefined` +- Type: `String|RegExp|Array` +- Default: `undefined` Files to include. @@ -151,8 +153,8 @@ module.exports = { ### `exclude` -Type: `String|RegExp|Array` -Default: `undefined` +- Type: `String|RegExp|Array` +- Default: `undefined` Files to exclude. @@ -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** @@ -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** @@ -222,12 +224,12 @@ module.exports = { ### `minify` -Type: `Function|Array` -Default: `CssMinimizerPlugin.cssnanoMinify` +- Type: `Function|Array` +- 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: @@ -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` @@ -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", ...}`, @@ -305,8 +307,8 @@ module.exports = { ### `minimizerOptions` -Type: `Object|Array` -Default: `{ preset: 'default' }` +- Type: `Object|Array` +- Default: `{ preset: 'default' }` Cssnano optimisations [options](https://cssnano.co/docs/what-are-optimisations/). @@ -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 = { @@ -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"; @@ -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** @@ -458,7 +460,7 @@ module.exports = { module: { rules: [ { - test: /.s?css$/, + test: /\.s?css$/, use: [ MiniCssExtractPlugin.loader, { loader: "css-loader", options: { sourceMap: true } }, @@ -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 = { @@ -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: [ @@ -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: [ @@ -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)