PostCSS Logo
Sponsored by Evil Martians
[![npm][npm]][npm-url] [![node][node]][node-url] [![deps][deps]][deps-url] [![tests][tests]][tests-url] [![coverage][cover]][cover-url] [![size][size]][size-url] Webpack chat: [![chat][chat]][chat-url] PostCSS chat: [![chat-postcss][chat-postcss]][chat-postcss-url] # postcss-loader Loader to process CSS with [`PostCSS`](https://github.com/postcss/postcss). ## 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 ``` or ```console pnpm add -D postcss-loader postcss ``` Then add the plugin to your `webpack` config. 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 = { 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"], }, ], }, }; ``` And run `webpack` via your preferred method. ## Options - [`execute`](#execute) - [`postcssOptions`](#postcssOptions) - [`sourceMap`](#sourcemap) - [`implementation`](#implementation) ### `execute` Type: ```ts type execute = boolean; ``` Default: `undefined` Enable PostCSS Parser support in `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` Type: ```ts type postcssOptions = | { from: string; map: boolean | SourceMapOptions; parser: string | object | (() => Parser); stringifier: Stringifier | Syntax; syntax: Syntax; to: string; } | ((loaderContext: LoaderContext) => { from: string; map: boolean | SourceMapOptions; parser: string | object | (() => Parser); stringifier: Stringifier | Syntax; syntax: Syntax; to: string; }); ``` Default: `undefined` Allows 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. #### `object` Setup `plugins`: **webpack.config.js** (**recommended**) ```js const myOtherPostcssPlugin = require("postcss-my-plugin"); module.exports = { module: { rules: [ { test: /\.sss$/i, loader: "postcss-loader", options: { postcssOptions: { plugins: [ "postcss-import", ["postcss-short", { prefix: "x" }], require.resolve("my-postcss-plugin"), myOtherPostcssPlugin({ myOption: true }), // Deprecated and will be removed in the next major release { "postcss-nested": { preserveEmpty: true } }, ], }, }, }, ], }, }; ``` **webpack.config.js** (**deprecated**, will be removed in the next major release) ```js module.exports = { module: { rules: [ { test: /\.sss$/i, loader: "postcss-loader", options: { postcssOptions: { plugins: { "postcss-import": {}, "postcss-short": { prefix: "x" }, }, }, }, }, ], }, }; ``` Setup `syntax`: **webpack.config.js** ```js module.exports = { module: { rules: [ { test: /\.sss$/i, loader: "postcss-loader", options: { postcssOptions: { // Can be `string` syntax: "sugarss", // Can be `object` syntax: require("sugarss"), }, }, }, ], }, }; ``` Setup `parser`: **webpack.config.js** ```js module.exports = { module: { rules: [ { test: /\.sss$/i, loader: "postcss-loader", options: { postcssOptions: { // Can be `string` parser: "sugarss", // Can be `object` parser: require("sugarss"), // Can be `function` parser: require("sugarss").parse, }, }, }, ], }, }; ``` Setup `stringifier`: **webpack.config.js** ```js const Midas = require("midas"); const midas = new Midas(); module.exports = { module: { rules: [ { test: /\.sss$/i, loader: "postcss-loader", options: { postcssOptions: { // Can be `string` stringifier: "sugarss", // Can be `object` stringifier: require("sugarss"), // Can be `function` stringifier: midas.stringifier, }, }, }, ], }, }; ``` #### `function` **webpack.config.js** ```js module.exports = { module: { rules: [ { test: /\.(css|sss)$/i, loader: "postcss-loader", options: { postcssOptions: (loaderContext) => { if (/\.sss$/.test(loaderContext.resourcePath)) { return { parser: "sugarss", plugins: [ ["postcss-short", { prefix: "x" }], "postcss-preset-env", ], }; } return { plugins: [ ["postcss-short", { prefix: "x" }], "postcss-preset-env", ], }; }, }, }, ], }, }; ``` #### `config` Type: ```ts type config = boolean | string; ``` Default: `undefined` Allows 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**) ##### Examples of Config Files Using `object` notation: **postcss.config.js** (**recommend**) ```js module.exports = { // You can specify any options from https://postcss.org/api/#processoptions here // parser: 'sugarss', plugins: [ // Plugins for PostCSS ["postcss-short", { prefix: "x" }], "postcss-preset-env", ], }; ``` Using `function` notation: **postcss.config.js** (**recommend**) ```js module.exports = (api) => { // `api.file` - path to the file // `api.mode` - `mode` value of webpack, please read https://webpack.js.org/configuration/mode/ // `api.webpackLoaderContext` - loader context for complex use cases // `api.env` - alias `api.mode` for compatibility with `postcss-cli` // `api.options` - the `postcssOptions` options if (/\.sss$/.test(api.file)) { return { // You can specify any options from https://postcss.org/api/#processoptions here parser: "sugarss", plugins: [ // Plugins for PostCSS ["postcss-short", { prefix: "x" }], "postcss-preset-env", ], }; } return { // You can specify any options from https://postcss.org/api/#processoptions here plugins: [ // Plugins for PostCSS ["postcss-short", { prefix: "x" }], "postcss-preset-env", ], }; }; ``` **postcss.config.js** (**deprecated**, will be removed in the next major release) ```js module.exports = { // You can specify any options from https://postcss.org/api/#processoptions here // parser: 'sugarss', plugins: { // Plugins for PostCSS "postcss-short": { prefix: "x" }, "postcss-preset-env": {}, }, }; ``` ##### Config Cascade You can use different `postcss.config.js` files in different directories. Config lookup starts from `path.dirname(file)` and walks the file tree upwards until a config file is found. ``` |– components | |– component | | |– index.js | | |– index.png | | |– style.css (1) | | |– postcss.config.js (1) | |– component | | |– index.js | | |– image.png | | |– style.css (2) | |– postcss.config.js (1 && 2 (recommended)) |– webpack.config.js | |– package.json ``` 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)). **webpack.config.js** (**recommended**) ```js module.exports = { module: { rules: [ { test: /\.css$/, use: [ "style-loader", { loader: "css-loader", options: { importLoaders: 1, }, }, "postcss-loader", ], }, ], }, }; ``` #### `boolean` Enables/Disables autoloading config. **webpack.config.js** ```js module.exports = { module: { rules: [ { test: /\.css$/i, loader: "postcss-loader", options: { postcssOptions: { config: false, }, }, }, ], }, }; ``` #### String Allows to specify the path to the config file. **webpack.config.js** ```js const path = require("path"); module.exports = { module: { rules: [ { test: /\.css$/i, loader: "postcss-loader", options: { postcssOptions: { config: path.resolve(__dirname, "custom.config.js"), }, }, }, ], }, }; ``` ### `sourceMap` Type: ```ts type sourceMap = boolean; ``` Default: depends on the `compiler.devtool` value 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 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 } }, ], }, ], }, }; ``` Alternative setup: **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" }, ], }, ], }, }; ``` ### `implementation` Type: ```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 module.exports = { module: { rules: [ { test: /\.css$/i, use: [ { loader: "style-loader" }, { loader: "css-loader" }, { loader: "postcss-loader", options: { implementation: require("postcss") }, }, { loader: "sass-loader" }, ], }, ], }, }; ``` #### String **webpack.config.js** ```js 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" }, ], }, ], }, }; ``` ## Examples ### SugarSS You'll need to install `sugarss`: ```console npm install --save-dev sugarss ``` Using [`SugarSS`](https://github.com/postcss/sugarss) syntax. **webpack.config.js** ```js 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 ``` Add vendor prefixes to CSS rules using [`autoprefixer`](https://github.com/postcss/autoprefixer). **webpack.config.js** ```js module.exports = { module: { rules: [ { test: /\.css$/i, use: [ "style-loader", { loader: "css-loader", options: { importLoaders: 1 }, }, { loader: "postcss-loader", options: { postcssOptions: { plugins: [ [ "autoprefixer", { // Options }, ], ], }, }, }, ], }, ], }, }; ``` > :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) ### PostCSS Preset Env You'll need to install `postcss-preset-env`: ```console npm install --save-dev postcss-preset-env ``` **webpack.config.js** ```js 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 }, ], ], }, }, }, ], }, ], }, }; ``` ### CSS Modules What is `CSS Modules`? Please [read](https://github.com/webpack-contrib/css-loader#modules). No additional options required on the `postcss-loader` side. To make them work properly, either add the `css-loader`’s `importLoaders` option. **webpack.config.js** ```js module.exports = { module: { rules: [ { test: /\.css$/i, use: [ "style-loader", { loader: "css-loader", options: { modules: true, importLoaders: 1, }, }, "postcss-loader", ], }, ], }, }; ``` ### CSS-in-JS and [`postcss-js`](https://github.com/postcss/postcss-js) You'll need to install `postcss-js`: ```console npm install --save-dev postcss-js ``` If you want to process styles written in JavaScript, use the [`postcss-js`](https://github.com/postcss/postcss-js) parser. **webpack.config.js** ```js 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", ], }, ], }, }; ``` As result you will be able to write styles in the following way ```js import colors from "./styles/colors"; export default { ".menu": { color: colors.main, height: 25, "&_link": { color: "white", }, }, }; ``` > :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). **webpack.config.js** ```js 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", }), ], }; ``` ### Emit assets To write a asset from PostCSS plugin to the webpack, need to add a message in `result.messages`. The message should contain the following fields: - `type` = `asset` - Message type (require, should be equal `asset`) - `file` - file name (require) - `content` - file content (require) - `sourceMap` - sourceMap - `info` - asset info **webpack.config.js** ```js const postcssCustomPlugin = (opts = {}) => { return { 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()], }, }, }, ], }, ], }, }; ``` ### Add dependencies, contextDependencies, buildDependencies, missingDependencies 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) **webpack.config.js** ```js const path = require("path"); const postcssCustomPlugin = (opts = {}) => { return { postcssPlugin: "postcss-custom-plugin", Once: (root, { result }) => { result.messages.push({ type: "dependency", file: path.resolve(__dirname, "path", "to", "file"), }); }, }; }; module.exports = { module: { rules: [ { test: /\.css$/i, use: [ "style-loader", "css-loader", { loader: "postcss-loader", options: { postcssOptions: { plugins: [postcssCustomPlugin()], }, }, }, ], }, ], }, }; ``` Or you can use ready-made plugin [postcss-add-dependencies](https://www.npmjs.com/package/postcss-add-dependencies). 2. Pass `loaderContext` in plugin. **webpack.config.js** ```js const path = require("path"); module.exports = { module: { rules: [ { test: /\.css$/i, use: [ "style-loader", "css-loader", { loader: "postcss-loader", options: { postcssOptions: { config: path.resolve(__dirname, "path/to/postcss.config.js"), }, }, }, ], }, ], }, }; ``` **postcss.config.js** ```js module.exports = (api) => ({ plugins: [ require("path/to/postcssCustomPlugin.js")({ loaderContext: api.webpackLoaderContext, }), ], }); ``` **postcssCustomPlugin.js** ```js const path = require("path"); const postcssCustomPlugin = (opts = {}) => { return { postcssPlugin: "postcss-custom-plugin", Once: (root, { result }) => { opts.loaderContext.addDependency( path.resolve(__dirname, "path", "to", "file") ); }, }; }; postcssCustomPlugin.postcss = true; module.exports = postcssCustomPlugin; ``` ## Contributing Please take a moment to read our contributing guidelines if you haven't yet done so. [CONTRIBUTING](./.github/CONTRIBUTING.md) ## License [MIT](./LICENSE) [npm]: https://img.shields.io/npm/v/postcss-loader.svg [npm-url]: https://npmjs.com/package/postcss-loader [node]: https://img.shields.io/node/v/postcss-loader.svg [node-url]: https://nodejs.org [deps]: https://david-dm.org/webpack-contrib/postcss-loader.svg [deps-url]: https://david-dm.org/webpack-contrib/postcss-loader [tests]: https://github.com/webpack-contrib/postcss-loader/workflows/postcss-loader/badge.svg [tests-url]: https://github.com/webpack-contrib/postcss-loader/actions [cover]: https://codecov.io/gh/webpack-contrib/postcss-loader/branch/master/graph/badge.svg [cover-url]: https://codecov.io/gh/webpack-contrib/postcss-loader [chat]: https://badges.gitter.im/webpack/webpack.svg [chat-url]: https://gitter.im/webpack/webpack [chat-postcss]: https://badges.gitter.im/postcss/postcss.svg [chat-postcss-url]: https://gitter.im/postcss/postcss [size]: https://packagephobia.now.sh/badge?p=postcss-loader [size-url]: https://packagephobia.now.sh/result?p=postcss-loader