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 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.
object
Setup plugins:
webpack.config.js (recommended)
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)
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)
Examples of Config Files
Using object notation:
postcss.config.js (recommend)
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)
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)
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.
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).
type of implementation should be the same as 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.
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.
✅ 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
We welcome all contributions!
If you're new here, please take a moment to review our contributing guidelines before submitting issues or pull requests.