webpack/postcss-loaderPublic

NotificationsYou must be signed in to change notification settings
Fork209
Star2.9k

PostCSS loader for webpack

License

MIT license

2.9k stars 209 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 543 Commits
.github		.github
.husky		.husky
src		src
test		test
.cspell.json		.cspell.json
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
babel.config.js		babel.config.js
commitlint.config.js		commitlint.config.js
jest.config.js		jest.config.js
lint-staged.config.js		lint-staged.config.js
package-lock.json		package-lock.json
package.json		package.json

Repository files navigation

Webpack chat:

PostCSS chat:

postcss-loader

Loader to process CSS withPostCSS.

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 installpostcss-loader andpostcss:

npm install --save-dev postcss-loader postcss

yarn add -D postcss-loader postcss

pnpm add -D postcss-loader postcss

Then add the plugin to yourwebpack config. For example:

In the following configuration the pluginpostcss-preset-env is used, which is not installed by default.

file.js

importcssfrom"file.css";

webpack.config.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 withconfig files:

postcss.config.js

module.exports={plugins:[["postcss-preset-env",{// Options},],],};

The loaderautomatically searches for configuration files.

webpack.config.js

module.exports={module:{rules:[{test:/\.css$/i,use:["style-loader","css-loader","postcss-loader"],},],},};

And runwebpack via your preferred method.

Options

`execute`

Type:

typeexecute=boolean;

Default:undefined

Enable PostCSS Parser support inCSS-in-JS.If you use JS styles thepostcss-js parser, add theexecute option.

webpack.config.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.

Type:

importtype{ConfigasPostCSSConfig}from"postcss-load-config";importtype{LoaderContext}from"webpack";typePostCSSLoaderContext=LoaderContext<PostCSSConfig>;interfacePostCSSLoaderAPI{mode:PostCSSLoaderContext["mode"];file:PostCSSLoaderContext["resourcePath"];webpackLoaderContext:PostCSSLoaderContext;env:PostCSSLoaderContext["mode"];options:PostCSSConfig;}exporttypePostCSSLoaderOptions=|PostCSSConfig|((api:PostCSSLoaderAPI)=>PostCSSConfig);

Default:undefined

Allows to setPostCSS options and plugins.

AllPostCSS options are supported.There is the specialconfig option for config files. How it works and how it can be configured is described below.

We recommend do not specifyfrom,to andmap options, because this can lead to wrong path in source maps.If you need source maps please use thesourcemap option.

For large projects, to optimize performance of the loader, it is better to providepostcssOptions in loaderconfig and specifyconfig: false. This approach removes the need to lookup and load external config files multipletimes during compilation.

`object`

Setupplugins:

webpack.config.js (recommended)

constmyOtherPostcssPlugin=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)

module.exports={module:{rules:[{test:/\.sss$/i,loader:"postcss-loader",options:{postcssOptions:{plugins:{"postcss-import":{},"postcss-short":{prefix:"x"},},},},},],},};

Setupsyntax:

webpack.config.js

module.exports={module:{rules:[{test:/\.sss$/i,loader:"postcss-loader",options:{postcssOptions:{// Can be `string`syntax:"sugarss",// Can be `object`syntax:require("sugarss"),},},},],},};

Setupparser:

webpack.config.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,},},},],},};

Setupstringifier:

webpack.config.js

constMidas=require("midas");constmidas=newMidas();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

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:

typeconfig=boolean|string;

Default:true

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:

apostcss property inpackage.json
a.postcssrc file in JSON or YAML format
a.postcssrc.json,.postcssrc.yaml,.postcssrc.yml,.postcssrc.js, or.postcssrc.cjs file
apostcss.config.js orpostcss.config.cjs CommonJS module exporting an object (recommended)

Examples of Config Files

Usingobject 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",],};

Usingfunction 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` optionsif(/\.sss$/.test(api.file)){return{// You can specify any options from https://postcss.org/api/#processoptions hereparser:"sugarss",plugins:[// Plugins for PostCSS["postcss-short",{prefix:"x"}],"postcss-preset-env",],};}return{// You can specify any options from https://postcss.org/api/#processoptions hereplugins:[// 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 differentpostcss.config.js files in different directories.Config lookup starts frompath.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 yourpostcss.config.js, addpostcss-loader to yourwebpack.config.js.You can use it standalone or in conjunction withcss-loader (recommended).

Use itbeforecss-loader andstyle-loader, butafter other preprocessor loaders like e.gsass|less|stylus-loader, if you use any (sincewebpack loaders evaluate right to left/bottom to top).

webpack.config.js (recommended)

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

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

constpath=require("path");module.exports={module:{rules:[{test:/\.css$/i,loader:"postcss-loader",options:{postcssOptions:{config:path.resolve(__dirname,"custom.config.js"),},},},],},};

`sourceMap`

Type:

typesourceMap=boolean;

Default: depends on thecompiler.devtool value

By default generation of source maps depends on thedevtool option.All values enable source map generation excepteval andfalse value.

webpack.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}},],},],},};

Alternative setup:

webpack.config.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:

typeimplementation=object;

type ofimplementation should be the same aspostcss.d.ts

Default:postcss

The specialimplementation option determines which implementation of PostCSS to use. Overrides the locally installedpeerDependency version ofpostcss.

This option is only really useful for downstream tooling authors to ease the PostCSS 7-to-8 transition.

`function`

webpack.config.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

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 installsugarss:

npm install --save-dev sugarss

UsingSugarSS syntax.

webpack.config.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 installautoprefixer:

npm install --save-dev autoprefixer

Add vendor prefixes to CSS rules usingautoprefixer.

webpack.config.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 includesautoprefixer, so adding it separately is not necessary if you already use the preset. Moreinformation

PostCSS Preset Env

You'll need to installpostcss-preset-env:

npm install --save-dev postcss-preset-env

webpack.config.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 isCSS Modules? Pleaseread.

No additional options required on thepostcss-loader side.To make them work properly, either add thecss-loader’simportLoaders option.

webpack.config.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`

You'll need to installpostcss-js:

npm install --save-dev postcss-js

If you want to process styles written in JavaScript, use thepostcss-js parser.

webpack.config.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

importcolorsfrom"./styles/colors";exportdefault{".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

Addbabel-plugin-add-module-exports to your configuration.
You need to have only onedefault export per style module.

Extract CSS

Usingmini-css-extract-plugin.

webpack.config.js

constisProductionMode=process.env.NODE_ENV==="production";constMiniCssExtractPlugin=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:[newMiniCssExtractPlugin({filename:isProductionMode ?"[name].[contenthash].css" :"[name].css",}),],};

Emit assets

To write a asset from PostCSS plugin to the webpack, need to add a message inresult.messages.

The message should contain the following fields:

type =asset - Message type (require, should be equalasset)
file - file name (require)
content - file content (require)
sourceMap - sourceMap
info - asset info

webpack.config.js

constpostcssCustomPlugin=(opts={})=>{return{postcssPlugin:"postcss-custom-plugin",Once:(root,{ result})=>{result.messages.push({type:"asset",file:"sprite.svg",content:"<svg>...</svg>",});},};};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:

(Recommended). The plugin may emit messages inresult.messages.

The message should contain the following fields:

type =dependency - Message type (require, should be equaldependency,context-dependency,build-dependency ormissing-dependency)
file - absolute file path (require)

webpack.config.js

constpath=require("path");constpostcssCustomPlugin=(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 pluginpostcss-add-dependencies.

PassloaderContext in plugin.

webpack.config.js

constpath=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

module.exports=(api)=>({plugins:[require("path/to/postcssCustomPlugin.js")({loaderContext:api.webpackLoaderContext,}),],});

postcssCustomPlugin.js

constpath=require("path");constpostcssCustomPlugin=(opts={})=>{return{postcssPlugin:"postcss-custom-plugin",Once:(root,{ result})=>{opts.loaderContext.addDependency(path.resolve(__dirname,"path","to","file"));},};};postcssCustomPlugin.postcss=true;module.exports=postcssCustomPlugin;