cb
-PostCSS Loader
-
-> Loads && processes CSS with [PostCSS](https://github.com/postcss/postcss)
-
-**Kind**: global function
-**Returns**: cb - cb Result
-**Requires**: module:path, module:loader-utils, module:schema-utils, module:postcss, module:postcss-load-config, module:Error
-**Version**: 2.0.0
-**Author**: Andrey Sitnik (@ai) String | Source |
-| map | Object | Source Map |
-
-
-* [loader(css, map)](#loader) ⇒ cb
- * [.cb](#loader.cb) : function
- * [.cb](#loader.cb) : function
-
-
-
-### loader.cb : function
-**Kind**: static typedef of [loader](#loader)
-
-| Param | Type | Description |
-| --- | --- | --- |
-| null | Object | Error |
-| result | String | Result (JS Module) |
-| map | Object | Source Map |
-
-
-
-### loader.cb : function
-**Kind**: static typedef of [loader](#loader)
-
-| Param | Type | Description |
-| --- | --- | --- |
-| null | Object | Error |
-| css | String | Result (Raw Module) |
-| map | Object | Source Map |
-
diff --git a/README.md b/README.md
index f7546968..a27a5b95 100644
--- a/README.md
+++ b/README.md
@@ -1,53 +1,495 @@
-[![npm][npm]][npm-url]
-[![node][node]][node-url]
-[![deps][deps]][deps-url]
-[![tests][tests]][tests-url]
-[![coverage][cover]][cover-url]
-[![chat][chat]][chat-url]
-
-
+ Install
+[![npm][npm]][npm-url] +[![node][node]][node-url] +[![tests][tests]][tests-url] +[![coverage][cover]][cover-url] +[![size][size]][size-url] + +Webpack discussion: [![discussion][discussion]][discussion-url] + +PostCSS chat: [![chat-postcss][chat-postcss]][chat-postcss-url] + +# postcss-loader + +A loader to process CSS using [`PostCSS`](https://github.com/postcss/postcss). -```bash -npm i -D postcss-loader +## Getting Started + +You need webpack v5 to use the latest version. For Webpack v4, you have to install postcss-loader v4. + +To begin, you'll need to install `postcss-loader` and `postcss`: + +```console +npm install --save-dev postcss-loader postcss +``` + +or + +```console +yarn add -D postcss-loader postcss ``` -Usage
+or -### `Configuration` +```console +pnpm add -D postcss-loader postcss +``` + +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. + +**file.js** + +```js +import css from "file.css"; +``` + +**webpack.config.js** + +```js +module.exports = { + module: { + rules: [ + { + test: /\.css$/i, + use: [ + "style-loader", + "css-loader", + { + loader: "postcss-loader", + options: { + postcssOptions: { + plugins: [ + [ + "postcss-preset-env", + { + // Options + }, + ], + ], + }, + }, + }, + ], + }, + ], + }, +}; +``` + +Alternative use with [config files](#config): **postcss.config.js** + ```js module.exports = { - parser: 'sugarss', - plugins: { - 'postcss-import': {}, - 'postcss-preset-env': {}, - 'cssnano': {} - } + plugins: [ + [ + "postcss-preset-env", + { + // Options + }, + ], + ], +}; +``` + +The loader **automatically** searches for configuration files. + +**webpack.config.js** + +```js +module.exports = { + module: { + rules: [ + { + test: /\.css$/i, + use: ["style-loader", "css-loader", "postcss-loader"], + }, + ], + }, +}; +``` + +Finally, run `webpack` using the method you normally use (e.g., via CLI or an npm script). + +## Options + +- [`execute`](#execute) +- [`postcssOptions`](#postcssOptions) +- [`sourceMap`](#sourcemap) +- [`implementation`](#implementation) + +### `execute` + +Type: + +```ts +type execute = boolean; +``` + +Default: `undefined` + +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** + +```js +module.exports = { + module: { + rules: [ + { + test: /\.style.js$/, + use: [ + "style-loader", + { loader: "css-loader" }, + { + loader: "postcss-loader", + options: { + postcssOptions: { parser: "postcss-js" }, + execute: true, + }, + }, + ], + }, + ], + }, +}; +``` + +### `postcssOptions` + +See the file [`./src/config.d.ts`](./src/config.d.ts). + +Type: + +```ts +import { type Config as PostCSSConfig } from "postcss-load-config"; +import { type LoaderContext } from "webpack"; + +type PostCSSLoaderContext = LoaderContextOptions
- -|Name|Type|Default|Description| -|:--:|:--:|:-----:|:----------| -|[`exec`](#exec)|`{Boolean}`|`undefined`|Enable PostCSS Parser support in `CSS-in-JS`| -|[`parser`](#syntaxes)|`{String\|Object}`|`undefined`|Set PostCSS Parser| -|[`syntax`](#syntaxes)|`{String\|Object}`|`undefined`|Set PostCSS Syntax| -|[`stringifier`](#syntaxes)|`{String\|Object}`|`undefined`|Set PostCSS Stringifier| -|[`config`](#config)|`{Object}`|`undefined`|Set `postcss.config.js` config path && `ctx`| -|[`plugins`](#plugins)|`{Array\|Function}`|`[]`|Set PostCSS Plugins| -|[`sourceMap`](#sourcemap)|`{String\|Boolean}`|`false`|Enable Source Maps| +#### String -### `Exec` +Allows to specify the path to the config file. -If you use JS styles without the [`postcss-js`][postcss-js] parser, add the `exec` option. +**webpack.config.js** ```js -{ - test: /\.style.js$/, - use: [ - 'style-loader', - { loader: 'css-loader', options: { importLoaders: 1 } }, - { loader: 'postcss-loader', options: { parser: 'sugarss', exec: true } } - ] -} -``` +const path = require("node:path"); -### `Config` +module.exports = { + module: { + rules: [ + { + test: /\.css$/i, + loader: "postcss-loader", + options: { + postcssOptions: { + config: path.resolve(__dirname, "custom.config.js"), + }, + }, + }, + ], + }, +}; +``` -|Name|Type|Default|Description| -|:--:|:--:|:-----:|:----------| -|[`path`](#path)|`{String}`|`undefined`|PostCSS Config Directory| -|[`context`](#context)|`{Object}`|`undefined`|PostCSS Config Context| +### `sourceMap` -#### `Path` +Type: -You can manually specify the path to search for your config (`postcss.config.js`) with the `config.path` option. This is needed if you store your config in a separate e.g `./config || ./.config` folder. +```ts +type sourceMap = boolean; +``` -> ⚠️ Otherwise it is **unnecessary** to set this option and is **not** recommended +Default: depends on the `compiler.devtool` value -> ⚠️ Note that you **can't** use a **filename** other than the [supported config formats] (e.g `.postcssrc.js`, `postcss.config.js`), this option only allows you to manually specify the **directory** where config lookup should **start** from +By default generation of source maps depends on the [`devtool`](https://webpack.js.org/configuration/devtool/) option. +All values enable source map generation except `eval` and `false` value. **webpack.config.js** + ```js -{ - loader: 'postcss-loader', - options: { - config: { - path: 'path/to/.config/' ✅ - path: 'path/to/.config/css.config.js' ❌ - } - } -} +module.exports = { + module: { + rules: [ + { + test: /\.css$/i, + use: [ + { loader: "style-loader" }, + { loader: "css-loader", options: { sourceMap: true } }, + { loader: "postcss-loader", options: { sourceMap: true } }, + { loader: "sass-loader", options: { sourceMap: true } }, + ], + }, + ], + }, +}; ``` -[supported config formats]: https://github.com/michael-ciniawsky/postcss-load-config#usage +Alternative setup: -#### `Context (ctx)` +**webpack.config.js** + +```js +module.exports = { + devtool: "source-map", + module: { + rules: [ + { + test: /\.css$/i, + use: [ + { loader: "style-loader" }, + { loader: "css-loader" }, + { loader: "postcss-loader" }, + { loader: "sass-loader" }, + ], + }, + ], + }, +}; +``` -|Name|Type|Default|Description| -|:--:|:--:|:-----:|:----------| -|`env`|`{String}`|`'development'`|`process.env.NODE_ENV`| -|`file`|`{Object}`|`loader.resourcePath`|`extname`, `dirname`, `basename`| -|`options`|`{Object}`|`{}`|Options| +### `implementation` -`postcss-loader` exposes context `ctx` to the config file, making your `postcss.config.js` dynamic, so can use it to do some real magic ✨ +Type: -**postcss.config.js** -```js -module.exports = ({ file, options, env }) => ({ - parser: file.extname === '.sss' ? 'sugarss' : false, - plugins: { - 'postcss-import': { root: file.dirname }, - 'postcss-preset-env': options['postcss-preset-env'] ? options['postcss-preset-env'] : false, - 'cssnano': env === 'production' ? options.cssnano : false - } -}) +```ts +type implementation = object; ``` +type of `implementation` should be the same as [postcss.d.ts](https://github.com/postcss/postcss/blob/main/lib/postcss.d.ts) + +Default: `postcss` + +The special `implementation` option determines which implementation of PostCSS to use. Overrides the locally installed `peerDependency` version of `postcss`. + +**This option is only really useful for downstream tooling authors to ease the PostCSS 7-to-8 transition.** + +#### `function` + **webpack.config.js** + ```js -{ - loader: 'postcss-loader', - options: { - config: { - ctx: { - 'postcss-preset-env': {...options}, - cssnano: {...options}, - } - } - } -} +module.exports = { + module: { + rules: [ + { + test: /\.css$/i, + use: [ + { loader: "style-loader" }, + { loader: "css-loader" }, + { + loader: "postcss-loader", + options: { implementation: require("postcss") }, + }, + { loader: "sass-loader" }, + ], + }, + ], + }, +}; ``` -### `Plugins` +#### String **webpack.config.js** + ```js -{ - loader: 'postcss-loader', - options: { - ident: 'postcss', - plugins: (loader) => [ - require('postcss-import')({ root: loader.resourcePath }), - require('postcss-preset-env')(), - require('cssnano')() - ] - } -} +module.exports = { + module: { + rules: [ + { + test: /\.css$/i, + use: [ + { loader: "style-loader" }, + { loader: "css-loader" }, + { + loader: "postcss-loader", + options: { implementation: require.resolve("postcss") }, + }, + { loader: "sass-loader" }, + ], + }, + ], + }, +}; ``` -> ⚠️ webpack requires an identifier (`ident`) in `options` when `{Function}/require` is used (Complex Options). The `ident` can be freely named as long as it is unique. It's recommended to name it (`ident: 'postcss'`) +## Examples -### `Syntaxes` +### SugarSS -|Name|Type|Default|Description| -|:--:|:--:|:-----:|:----------| -|[`parser`](#parser)|`{String\|Function}`|`undefined`|Custom PostCSS Parser| -|[`syntax`](#syntax)|`{String\|Function}`|`undefined`|Custom PostCSS Syntax| -|[`stringifier`](#stringifier)|`{String\|Function}`|`undefined`|Custom PostCSS Stringifier| +`SugarSS` is a whitespace-based syntax for PostCSS. -#### `Parser` +You'll need to install `sugarss`: -**webpack.config.js** -```js -{ - test: /\.sss$/, - use: [ - ..., - { loader: 'postcss-loader', options: { parser: 'sugarss' } } - ] -} +```console +npm install --save-dev sugarss ``` -#### `Syntax` +Using [`SugarSS`](https://github.com/postcss/sugarss) syntax. **webpack.config.js** + ```js -{ - test: /\.css$/, - use: [ - ..., - { loader: 'postcss-loader', options: { syntax: 'sugarss' } } - ] -} +module.exports = { + module: { + rules: [ + { + test: /\.sss$/i, + use: [ + "style-loader", + { loader: "css-loader", options: { importLoaders: 1 } }, + { + loader: "postcss-loader", + options: { postcssOptions: { parser: "sugarss" } }, + }, + ], + }, + ], + }, +}; +``` + +### Autoprefixer + +You'll need to install `autoprefixer`: + +```console +npm install --save-dev autoprefixer ``` -#### `Stringifier` +Automatically add vendor prefixes to CSS rules using [`autoprefixer`](https://github.com/postcss/autoprefixer). **webpack.config.js** + ```js -{ - test: /\.css$/, - use: [ - ..., - { loader: 'postcss-loader', options: { stringifier: 'midas' } } - ] -} +module.exports = { + module: { + rules: [ + { + test: /\.css$/i, + use: [ + "style-loader", + { loader: "css-loader", options: { importLoaders: 1 } }, + { + loader: "postcss-loader", + options: { + postcssOptions: { + plugins: [ + [ + "autoprefixer", + { + // Autoprefixer options (optional) + }, + ], + ], + }, + }, + }, + ], + }, + ], + }, +}; ``` -### `SourceMap` +> [!WARNING] +> +> [`postcss-preset-env`](https://github.com/csstools/postcss-preset-env) includes [`autoprefixer`](https://github.com/postcss/autoprefixer), so adding it separately is not necessary if you already use the preset. More [information](https://github.com/csstools/postcss-preset-env#autoprefixer) -Enables source map support, `postcss-loader` will use the previous source map given by other loaders and update it accordingly, if no previous loader is applied before `postcss-loader`, the loader will generate a source map for you. +### PostCSS Preset Env + +You'll need to install `postcss-preset-env`: + +```console +npm install --save-dev postcss-preset-env +``` **webpack.config.js** + ```js -{ - test: /\.css/, - use: [ - { loader: 'style-loader', options: { sourceMap: true } }, - { loader: 'css-loader', options: { sourceMap: true } }, - { loader: 'postcss-loader', options: { sourceMap: true } }, - { loader: 'sass-loader', options: { sourceMap: true } } - ] -} +module.exports = { + module: { + rules: [ + { + test: /\.css$/i, + use: [ + "style-loader", + { loader: "css-loader", options: { importLoaders: 1 } }, + { + loader: "postcss-loader", + options: { + postcssOptions: { + plugins: [ + [ + "postcss-preset-env", + { + // Options + }, + ], + ], + }, + }, + }, + ], + }, + ], + }, +}; ``` -#### `'inline'` +### CSS Modules + +> What are `CSS Modules`? Please [read here](https://github.com/webpack/css-loader#modules). -You can set the `sourceMap: 'inline'` option to inline the source map -within the CSS directly as an annotation comment. +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** + ```js -{ - loader: 'postcss-loader', - options: { - sourceMap: 'inline' - } -} +module.exports = { + module: { + rules: [ + { + test: /\.css$/i, + use: [ + "style-loader", + { + loader: "css-loader", + options: { modules: true, importLoaders: 1 }, + }, + "postcss-loader", + ], + }, + ], + }, +}; ``` -```css -.class { color: red; } +### CSS-in-JS and [`postcss-js`](https://github.com/postcss/postcss-js) -/*# sourceMappingURL=data:application/json;base64, ... */ -``` +To process styles written in JavaScript, you can use `postcss-js` as the parser. + +You'll need to install `postcss-js`: -Examples
+```console +npm install --save-dev postcss-js +``` -### `Stylelint` +If you want to process styles written in JavaScript, use the [`postcss-js`](https://github.com/postcss/postcss-js) parser. **webpack.config.js** + ```js -{ - test: /\.css$/, - use: [ - 'style-loader', - 'css-loader', - { - loader: 'postcss-loader', - options: { - ident: 'postcss', - plugins: [ - require('postcss-import')(), - require('stylelint')(), - ..., - ] - } - } - ] -} +module.exports = { + module: { + rules: [ + { + test: /\.style.js$/, + use: [ + "style-loader", + { loader: "css-loader", options: { importLoaders: 2 } }, + { + loader: "postcss-loader", + options: { + postcssOptions: { parser: "postcss-js" }, + execute: true, + }, + }, + "babel-loader", + ], + }, + ], + }, +}; ``` -### Autoprefixing +As result you will be able to write styles in the following way: -**webpack.config.js** ```js -{ - test: /\.css$/, - use: [ - 'style-loader', - 'css-loader', - { - loader: 'postcss-loader', - options: { - ident: 'postcss', - plugins: [ - require('autoprefixer')({...options}), - ..., - ] - } - } - ] -} +import colors from "./styles/colors"; + +export default { + ".menu": { color: colors.main, height: 25, "&_link": { color: "white" } }, +}; ``` -> :warning: [`postcss-preset-env`](https://github.com/csstools/postcss-preset-env) includes [`autoprefixer`](https://github.com/postcss/autoprefixer), so adding it separately is not necessary if you already use the preset. +> [!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. -### `CSS Modules` +### Extract CSS -This loader [cannot be used] with [CSS Modules] out of the box due -to the way `css-loader` processes file imports. To make them work properly, -either add the css-loader’s [`importLoaders`] option. +To extract CSS into separate files, use [`mini-css-extract-plugin`](https://github.com/webpack/mini-css-extract-plugin). **webpack.config.js** + ```js -{ - test: /\.css$/, - use: [ - 'style-loader', - { loader: 'css-loader', options: { modules: true, importLoaders: 1 } }, - 'postcss-loader' - ] -} +const isProductionMode = process.env.NODE_ENV === "production"; + +const MiniCssExtractPlugin = require("mini-css-extract-plugin"); + +module.exports = { + mode: isProductionMode ? "production" : "development", + module: { + rules: [ + { + test: /\.css$/, + use: [ + isProductionMode ? MiniCssExtractPlugin.loader : "style-loader", + "css-loader", + "postcss-loader", + ], + }, + ], + }, + plugins: [ + new MiniCssExtractPlugin({ + filename: isProductionMode ? "[name].[contenthash].css" : "[name].css", + }), + ], +}; ``` -or use [postcss-modules] instead of `css-loader`. +> 💡 Use this setup to extract and cache CSS in production while keeping fast style injection during development. + +### Emit assets -[`importLoaders`]: https://github.com/webpack-contrib/css-loader#importloaders -[cannot be used]: https://github.com/webpack/css-loader/issues/137 -[CSS Modules]: https://github.com/webpack/css-loader#css-modules -[postcss-modules]: https://github.com/css-modules/postcss-modules +To emit an asset from PostCSS plugin to the webpack, need to add a message in `result.messages`. -### `CSS-in-JS` +The message should contain the following fields: -If you want to process styles written in JavaScript, use the [postcss-js] parser. +- `type` = `asset` - Message type (require, should be equal `asset`) +- `file` - file name (require) +- `content` - file content (require) +- `sourceMap` - sourceMap +- `info` - asset info -[postcss-js]: https://github.com/postcss/postcss-js +**webpack.config.js** ```js -{ - test: /\.style.js$/, - use: [ - 'style-loader', - { loader: 'css-loader', options: { importLoaders: 2 } }, - { loader: 'postcss-loader', options: { parser: 'postcss-js' } }, - 'babel-loader' - ] -} +const postcssCustomPlugin = (opts = {}) => ({ + postcssPlugin: "postcss-custom-plugin", + Once: (root, { result }) => { + result.messages.push({ + type: "asset", + file: "sprite.svg", + content: "", + }); + }, +}); + +module.exports = { + module: { + rules: [ + { + test: /\.css$/i, + use: [ + "style-loader", + "css-loader", + { + loader: "postcss-loader", + options: { postcssOptions: { plugins: [postcssCustomPlugin()] } }, + }, + ], + }, + ], + }, +}; ``` -As result you will be able to write styles in the following way +> ℹ️ This allows your plugin to generate additional files as part of the build process, and Webpack will handle them like any other emitted asset. -```js -import colors from './styles/colors' +### Add dependencies, contextDependencies, buildDependencies, missingDependencies -export default { - '.menu': { - color: colors.main, - height: 25, - '&_link': { - color: 'white' - } - } -} -``` +The dependencies are necessary for webpack to understand when it needs to run recompilation on the changed files. + +There are two way to add dependencies: + +1. (Recommended). The plugin may emit messages in `result.messages`. + +The message should contain the following fields: + +- `type` = `dependency` - Message type (require, should be equal `dependency`, `context-dependency`, `build-dependency` or `missing-dependency`) +- `file` - absolute file path (require) -> :warning: If you are using Babel you need to do the following in order for the setup to work +**webpack.config.js** -> 1. Add [babel-plugin-add-module-exports] to your configuration -> 2. You need to have only one **default** export per style module +```js +const path = require("node:path"); + +const postcssCustomPlugin = (opts = {}) => ({ + postcssPlugin: "postcss-custom-plugin", + Once: (root, { result }) => { + result.messages.push({ + type: "dependency", + file: path.resolve(__dirname, "path", "to", "file"), + }); + }, +}); -[babel-plugin-add-module-exports]: https://github.com/59naga/babel-plugin-add-module-exports +module.exports = { + module: { + rules: [ + { + test: /\.css$/i, + use: [ + "style-loader", + "css-loader", + { + loader: "postcss-loader", + options: { postcssOptions: { plugins: [postcssCustomPlugin()] } }, + }, + ], + }, + ], + }, +}; +``` -### [Extract CSS][ExtractPlugin] +> 💡 You can use ready-made plugin [postcss-add-dependencies](https://www.npmjs.com/package/postcss-add-dependencies) to simplify this process. -[ExtractPlugin]: https://github.com/webpack-contrib/mini-css-extract-plugin +2. Pass `loaderContext` in plugin (for advanced setups). **webpack.config.js** + ```js -const MiniCssExtractPlugin = require('mini-css-extract-plugin'); -const devMode = process.env.NODE_ENV !== 'production'; +const path = require("node:path"); module.exports = { module: { rules: [ { - test: /\.css$/, + test: /\.css$/i, use: [ - devMode ? 'style-loader' : MiniCssExtractPlugin.loader, - 'css-loader', - 'postcss-loader', - ] - } - ] + "style-loader", + "css-loader", + { + loader: "postcss-loader", + options: { + postcssOptions: { + config: path.resolve(__dirname, "path/to/postcss.config.js"), + }, + }, + }, + ], + }, + ], }, +}; +``` + +> ⚠️ 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: [ - new MiniCssExtractPlugin({ - filename: devMode ? '[name].css' : '[name].[hash].css', - }) - ] -} + require("path/to/postcssCustomPlugin.js")({ + loaderContext: api.webpackLoaderContext, + }), + ], +}); ``` -Maintainers
- -
-
- 
-
- Michael Ciniawsky
-
- |
-
-
- 
-
- Alexander Krasnoyarov
-
- |
-
a {
+ color: black;
+}
+
+a {
+ color: red;
+}
+
+a {
+ color: green;
+}
+
+a {
+ color: blue;
+}
+
+.class {
+ -x-border-color: blue blue *;
+ -x-color: * #fafafa;
+}
+
+.class-foo {
+ -z-border-color: blue blue *;
+ -z-color: * #fafafa;
+}
+
+.phone {
+ _title {
+ width: 500px;
+
+ @media (max-width: 500px) {
+ width: auto;
+ }
+
+ body.is_dark {
+ color: white;
+ }
+ }
+
+ img {
+ display: block;
+ }
+}
+