From 9f539648fb46264678f7807ed377ea297d045656 Mon Sep 17 00:00:00 2001 From: Sachin Kumar Date: Sat, 31 May 2025 10:16:35 +0530 Subject: [PATCH] docs: fix typos and improve clarity in README.md --- README.md | 68 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 42 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 31a31f13..f92ae5ab 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ PostCSS chat: [![chat-postcss][chat-postcss]][chat-postcss-url] # postcss-loader -Loader to process CSS with [`PostCSS`](https://github.com/postcss/postcss). +A loader to process CSS using [`PostCSS`](https://github.com/postcss/postcss). ## Getting Started @@ -60,7 +60,7 @@ or pnpm add -D postcss-loader postcss ``` -Then add the plugin to your `webpack` config. For example: +Then add the loader to your `webpack` configuration. For example: > In the following configuration the plugin [`postcss-preset-env`](https://github.com/csstools/postcss-preset-env) is used, which is not installed by default. @@ -137,7 +137,7 @@ module.exports = { }; ``` -And run `webpack` via your preferred method. +Finally, run `webpack` using the method you normally use (e.g., via CLI or an npm script). ## Options @@ -156,7 +156,7 @@ type execute = boolean; Default: `undefined` -Enable PostCSS Parser support in `CSS-in-JS`. +Enable PostCSS parser support for `CSS-in-JS`. If you use JS styles the [`postcss-js`](https://github.com/postcss/postcss-js) parser, add the `execute` option. **webpack.config.js** @@ -215,17 +215,16 @@ export type PostCSSLoaderOptions = Default: `undefined` -Allows to set [`PostCSS options`](https://postcss.org/api/#processoptions) and plugins. +Allows you to set [`PostCSS options`](https://postcss.org/api/#processoptions) and plugins. All `PostCSS` options are supported. There is the special `config` option for config files. How it works and how it can be configured is described below. We recommend do not specify `from`, `to` and `map` options, because this can lead to wrong path in source maps. -If you need source maps please use the [`sourcemap`](#sourcemap) option. +If you need source maps please use the [`sourcemap`](#sourcemap) option instead. -For large projects, to optimize performance of the loader, it is better to provide `postcssOptions` in loader -config and specify `config: false`. This approach removes the need to lookup and load external config files multiple -times during compilation. +For large projects, to optimize performance of the loader, it is better to provide `postcssOptions` in loader config and specify `config: false`. +This approach removes the need to lookup and load external config files multiple times during compilation. #### `object` @@ -412,17 +411,17 @@ type config = boolean | string; Default: `true` -Allows to set options using config files. +Allows you to set options using config files. Options specified in the config file are combined with options passed to the loader, the loader options overwrite options from config. ##### Config Files The loader will search up the directory tree for configuration in the following places: -- a `postcss` property in `package.json` -- a `.postcssrc` file in JSON or YAML format -- a `.postcssrc.json`, `.postcssrc.yaml`, `.postcssrc.yml`, `.postcssrc.js`, or `.postcssrc.cjs` file -- a `postcss.config.js` or `postcss.config.cjs` CommonJS module exporting an object (**recommended**) +- A `postcss` property in `package.json` +- A `.postcssrc` file in JSON or YAML format +- A `.postcssrc.json`, `.postcssrc.yaml`, `.postcssrc.yml`, `.postcssrc.js`, or `.postcssrc.cjs` file +- A `postcss.config.js` or `postcss.config.cjs` CommonJS module exporting an object (**recommended**) ##### Examples of Config Files @@ -517,7 +516,7 @@ Config lookup starts from `path.dirname(file)` and walks the file tree upwards u After setting up your `postcss.config.js`, add `postcss-loader` to your `webpack.config.js`. You can use it standalone or in conjunction with `css-loader` (recommended). -Use it **before** `css-loader` and `style-loader`, but **after** other preprocessor loaders like e.g `sass|less|stylus-loader`, if you use any (since [webpack loaders evaluate right to left/bottom to top](https://webpack.js.org/concepts/loaders/#configuration)). +Use `postcss-loader` **before** `css-loader` and `style-loader`, but **after** other preprocessor loaders like e.g `sass|less|stylus-loader`, if you use any (since [webpack loaders evaluate right to left/bottom to top](https://webpack.js.org/concepts/loaders/#configuration)). **webpack.config.js** (**recommended**) @@ -719,6 +718,8 @@ module.exports = { ### SugarSS +`SugarSS` is a whitespace-based syntax for PostCSS. + You'll need to install `sugarss`: ```console @@ -764,7 +765,7 @@ You'll need to install `autoprefixer`: npm install --save-dev autoprefixer ``` -Add vendor prefixes to CSS rules using [`autoprefixer`](https://github.com/postcss/autoprefixer). +Automatically add vendor prefixes to CSS rules using [`autoprefixer`](https://github.com/postcss/autoprefixer). **webpack.config.js** @@ -788,7 +789,7 @@ module.exports = { [ "autoprefixer", { - // Options + // Autoprefixer options (optional) }, ], ], @@ -852,9 +853,9 @@ module.exports = { ### CSS Modules -What is `CSS Modules`? Please [read](https://github.com/webpack-contrib/css-loader#modules). +> What are `CSS Modules`? Please [read here](https://github.com/webpack-contrib/css-loader#modules). -No additional options required on the `postcss-loader` side. +No additional options required on the `postcss-loader` side to support CSS Modules. To make them work properly, either add the `css-loader`’s `importLoaders` option. **webpack.config.js** @@ -884,6 +885,8 @@ module.exports = { ### CSS-in-JS and [`postcss-js`](https://github.com/postcss/postcss-js) +To process styles written in JavaScript, you can use `postcss-js` as the parser. + You'll need to install `postcss-js`: ```console @@ -925,7 +928,7 @@ module.exports = { }; ``` -As result you will be able to write styles in the following way +As result you will be able to write styles in the following way: ```js import colors from "./styles/colors"; @@ -944,13 +947,13 @@ export default { > [!WARNING] > > If you are using Babel you need to do the following in order for the setup to work - +> > 1. Add [`babel-plugin-add-module-exports`](https://github.com/59naga/babel-plugin-add-module-exports) to your configuration. > 2. You need to have only one **default** export per style module. ### Extract CSS -Using [`mini-css-extract-plugin`](https://github.com/webpack-contrib/mini-css-extract-plugin). +To extract CSS into separate files, use [`mini-css-extract-plugin`](https://github.com/webpack-contrib/mini-css-extract-plugin). **webpack.config.js** @@ -981,9 +984,11 @@ module.exports = { }; ``` +> 💡 Use this setup to extract and cache CSS in production while keeping fast style injection during development. + ### Emit assets -To write a asset from PostCSS plugin to the webpack, need to add a message in `result.messages`. +To emit an asset from PostCSS plugin to the webpack, need to add a message in `result.messages`. The message should contain the following fields: @@ -1032,6 +1037,8 @@ module.exports = { }; ``` +> ℹ️ This allows your plugin to generate additional files as part of the build process, and Webpack will handle them like any other emitted asset. + ### Add dependencies, contextDependencies, buildDependencies, missingDependencies The dependencies are necessary for webpack to understand when it needs to run recompilation on the changed files. @@ -1085,9 +1092,9 @@ module.exports = { }; ``` -Or you can use ready-made plugin [postcss-add-dependencies](https://www.npmjs.com/package/postcss-add-dependencies). +> 💡 You can use ready-made plugin [postcss-add-dependencies](https://www.npmjs.com/package/postcss-add-dependencies) to simplify this process. -2. Pass `loaderContext` in plugin. +2. Pass `loaderContext` in plugin (for advanced setups). **webpack.config.js** @@ -1117,8 +1124,12 @@ module.exports = { }; ``` +> ⚠️ Use this approach only when managing dependencies via custom PostCSS configurations with dynamic imports or external files. + **postcss.config.js** +Pass the `webpackLoaderContext` through the PostCSS `api` object: + ```js module.exports = (api) => ({ plugins: [ @@ -1131,6 +1142,8 @@ module.exports = (api) => ({ **postcssCustomPlugin.js** +Register a file dependency using `loaderContext.addDependency`: + ```js const path = require("path"); @@ -1149,9 +1162,12 @@ postcssCustomPlugin.postcss = true; module.exports = postcssCustomPlugin; ``` +> ✅ This method is ideal when you want to dynamically declare dependencies without relying on result.messages, especially in more complex setups or shared plugin configurations. + ## 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 before submitting issues or pull requests. [CONTRIBUTING](./.github/CONTRIBUTING.md)