postcss-loader

Loader for webpack to process CSS with PostCSS

Install

  1. npm i -D postcss-loader

Usage

#

postcss.config.js

  1. module.exports = {
  2.   parser: 'sugarss',
  3.   plugins: {
  4.     'postcss-import': {},
  5.     'postcss-preset-env': {},
  6.     'cssnano': {}
  7.   }
  8. }

You can read more about common PostCSS Config here.

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.

  1. |– components
  2. | |– component
  3. | | |– index.js
  4. | | |– index.png
  5. | | |– style.css (1)
  6. | | |– postcss.config.js (1)
  7. | |– component
  8. | | |– index.js
  9. | | |– image.png
  10. | | |– style.css (2)
  11. |
  12. |– postcss.config.js (1 && 2 (recommended))
  13. |– webpack.config.js
  14. |
  15. |– 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 after css-loader and style-loader, but before other preprocessor loaders like e.g sass|less|stylus-loader, if you use any.

webpack.config.js

  1. module.exports = {
  2.   module: {
  3.     rules: [
  4.       {
  5.         test: /\.css$/,
  6.         use: [ 'style-loader', 'postcss-loader' ]
  7.       }
  8.     ]
  9.   }
  10. }

⚠️ When postcss-loader is used standalone (without css-loader) don’t use @import in your CSS, since this can lead to quite bloated bundles

webpack.config.js (recommended)

  1. module.exports = {
  2.   module: {
  3.     rules: [
  4.       {
  5.         test: /\.css$/,
  6.         use: [
  7.           'style-loader',
  8.           { loader: 'css-loader', options: { importLoaders: 1 } },
  9.           'postcss-loader'
  10.         ]
  11.       }
  12.     ]
  13.   }
  14. }

Options

Name

Type

Default

Description

Name

exec

Type

{Boolean}

Default

undefined

Description

Enable PostCSS Parser support in CSS-in-JS

Name

parser

Type

{String|Object}

Default

undefined

Description

Set PostCSS Parser

Name

syntax

Type

{String|Object}

Default

undefined

Description

Set PostCSS Syntax

Name

stringifier

Type

{String|Object}

Default

undefined

Description

Set PostCSS Stringifier

Name

config

Type

{Object}

Default

undefined

Description

Set postcss.config.js config path && ctx

Name

plugins

Type

{Array|Function}

Default

[]

Description

Set PostCSS Plugins

Name

sourceMap

Type

{String|Boolean}

Default

false

Description

Enable Source Maps

Exec

If you use JS styles without the [postcss-js][postcss-js] parser, add the exec option.

webpack.config.js

  1. {
  2.   test: /\.style.js$/,
  3.   use: [
  4.     'style-loader',
  5.     { loader: 'css-loader', options: { importLoaders: 1 } },
  6.     { loader: 'postcss-loader', options: { parser: 'sugarss', exec: true } }
  7.   ]
  8. }

Config

Name

Type

Default

Description

Name

path

Type

{String}

Default

undefined

Description

PostCSS Config Directory

Name

context

Type

{Object}

Default

undefined

Description

PostCSS Config Context

Path

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.

⚠️ Otherwise it is unnecessary to set this option and is not recommended

⚠️ 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

webpack.config.js

  1. {
  2.   loader: 'postcss-loader',
  3.   options: {
  4.     config: {
  5.       path: 'path/to/.config/' ✅
  6.       path: 'path/to/.config/css.config.js' ❌
  7.     }
  8.   }
  9. }

Context (ctx)

Name

Type

Default

Description

Name

env

Type

{String}

Default

'development'

Description

process.env.NODE_ENV

Name

file

Type

{Object}

Default

loader.resourcePath

Description

extname, dirname, basename

Name

options

Type

{Object}

Default

{}

Description

Options

postcss-loader exposes context ctx to the config file, making your postcss.config.js dynamic, so can use it to do some real magic ✨

postcss.config.js

  1. module.exports = ({ file, options, env }) => ({
  2.   parser: file.extname === '.sss' ? 'sugarss' : false,
  3.   plugins: {
  4.     'postcss-import': { root: file.dirname },
  5.     'postcss-preset-env': options['postcss-preset-env'] ? options['postcss-preset-env'] : false,
  6.     'cssnano': env === 'production' ? options.cssnano : false
  7.   }
  8. })

webpack.config.js

  1. {
  2.   loader: 'postcss-loader',
  3.   options: {
  4.     config: {
  5.       ctx: {
  6.         'postcss-preset-env': {...options},
  7.         cssnano: {...options},
  8.       }
  9.     }
  10.   }
  11. }

Plugins

webpack.config.js

  1. {
  2.   loader: 'postcss-loader',
  3.   options: {
  4.     ident: 'postcss',
  5.     plugins: (loader) => [
  6.       require('postcss-import')({ root: loader.resourcePath }),
  7.       require('postcss-preset-env')(),
  8.       require('cssnano')()
  9.     ]
  10.   }
  11. }

⚠️ 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')

Syntaxes

Name

Type

Default

Description

Name

parser

Type

{String|Function}

Default

undefined

Description

Custom PostCSS Parser

Name

syntax

Type

{String|Function}

Default

undefined

Description

Custom PostCSS Syntax

Name

stringifier

Type

{String|Function}

Default

undefined

Description

Custom PostCSS Stringifier

Parser

webpack.config.js

  1. {
  2.   test: /\.sss$/,
  3.   use: [
  4.     ...,
  5.     { loader: 'postcss-loader', options: { parser: 'sugarss' } }
  6.   ]
  7. }

Syntax

webpack.config.js

  1. {
  2.   test: /\.css$/,
  3.   use: [
  4.     ...,
  5.     { loader: 'postcss-loader', options: { syntax: 'sugarss' } }
  6.   ]
  7. }

Stringifier

webpack.config.js

  1. {
  2.   test: /\.css$/,
  3.   use: [
  4.     ...,
  5.     { loader: 'postcss-loader', options: { stringifier: 'midas' } }
  6.   ]
  7. }

SourceMap

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.

webpack.config.js

  1. {
  2.   test: /\.css/,
  3.   use: [
  4.     { loader: 'style-loader', options: { sourceMap: true } },
  5.     { loader: 'css-loader', options: { sourceMap: true } },
  6.     { loader: 'postcss-loader', options: { sourceMap: true } },
  7.     { loader: 'sass-loader', options: { sourceMap: true } }
  8.   ]
  9. }

'inline'

You can set the sourceMap: 'inline' option to inline the source map within the CSS directly as an annotation comment.

webpack.config.js

  1. {
  2.   loader: 'postcss-loader',
  3.   options: {
  4.     sourceMap: 'inline'
  5.   }
  6. }
  1. .class { color: red; }
  3. /*# sourceMappingURL=data:application/json;base64, ... */

Examples

Stylelint

webpack.config.js

  1. {
  2.   test: /\.css$/,
  3.   use: [
  4.     'style-loader',
  5.     'css-loader',
  6.     {
  7.       loader: 'postcss-loader',
  8.       options: {
  9.         ident: 'postcss',
  10.         plugins: [
  11.           require('postcss-import')(),
  12.           require('stylelint')(),
  13.           ...,
  14.         ]
  15.       }
  16.     }
  17.   ]
  18. }

Autoprefixing

webpack.config.js

  1. {
  2.   test: /\.css$/,
  3.   use: [
  4.     'style-loader',
  5.     'css-loader',
  6.     {
  7.       loader: 'postcss-loader',
  8.       options: {
  9.         ident: 'postcss',
  10.         plugins: [
  11.           require('autoprefixer')({...options}),
  12.           ...,
  13.         ]
  14.       }
  15.     }
  16.   ]
  17. }

:warning: postcss-preset-env includes autoprefixer, so adding it separately is not necessary if you already use the preset.

CSS Modules

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.

webpack.config.js

  1. {
  2.   test: /\.css$/,
  3.   use: [
  4.     'style-loader',
  5.     { loader: 'css-loader', options: { modules: true, importLoaders: 1 } },
  6.     'postcss-loader'
  7.   ]
  8. }

or use [postcss-modules] instead of css-loader.

CSS-in-JS

If you want to process styles written in JavaScript, use the [postcss-js] parser.

webpack.config.js

  1. {
  2.   test: /\.style.js$/,
  3.   use: [
  4.     'style-loader',
  5.     { loader: 'css-loader', options: { importLoaders: 2 } },
  6.     { loader: 'postcss-loader', options: { parser: 'postcss-js' } },
  7.     'babel-loader'
  8.   ]
  9. }

As result you will be able to write styles in the following way

  1. import colors from './styles/colors'
  3. export default {
  4.     '.menu': {
  5.       color: colors.main,
  6.       height: 25,
  7.       '&_link': {
  8.       color: 'white'
  9.     }
  10.   }
  11. }

:warning: If you are using Babel you need to do the following in order for the setup to work

NaN. Add [babel-plugin-add-module-exports] to your configuration NaN. You need to have only one default export per style module

[Extract CSS][ExtractPlugin]

webpack.config.js

  1. const devMode = process.env.NODE_ENV !== 'production'
  3. const MiniCssExtractPlugin = require('mini-css-extract-plugin')
  5. module.exports = {
  6.   module: {
  7.     rules: [
  8.       {
  9.         test: /\.css$/,
  10.         use: [
  11.           devMode ? 'style-loader' : MiniCssExtractPlugin.loader,
  12.           'css-loader',
  13.           'postcss-loader'
  14.         ]
  15.       }
  16.     ]
  17.   },
  18.   plugins: [
  19.     new MiniCssExtractPlugin({
  20.       filename: devMode ? '[name].css' : '[name].[hash].css'
  21.     })
  22.   ]
  23. }

Maintainers

postcss-loader - 图1


  1.       Michael Ciniawsky

postcss-loader - 图2


  1.       Alexander Krasnoyarov