Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

postcss-loader

3.0.0 • Public • Published a month ago

PostCSS Loader

Loader for webpack to process CSS with PostCSS

Install

npm i -D postcss-loader

Usage

`Configuration`

postcss.config.js

module.exports = {
  parser: 'sugarss',
  plugins: {
    'postcss-import': {},
    'postcss-preset-env': {},
    'cssnano': {}
  }
}

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.

|– 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 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

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

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          { loader: 'css-loader', options: { importLoaders: 1 } },
          'postcss-loader'
        ]
      }
    ]
  }
}

Options

Name	Type	Default	Description
`exec`	`{Boolean}`	`undefined`	Enable PostCSS Parser support in `CSS-in-JS`
`parser`	`{String\\|Object}`	`undefined`	Set PostCSS Parser
`syntax`	`{String\\|Object}`	`undefined`	Set PostCSS Syntax
`stringifier`	`{String\\|Object}`	`undefined`	Set PostCSS Stringifier
`config`	`{Object}`	`undefined`	Set `postcss.config.js` config path && `ctx`
`plugins`	`{Array\\|Function}`	`[]`	Set PostCSS Plugins
`sourceMap`	`{String\\|Boolean}`	`false`	Enable Source Maps

`Exec`

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

webpack.config.js

{
  test: /\.style.js$/,
  use: [
    'style-loader',
    { loader: 'css-loader', options: { importLoaders: 1 } },
    { loader: 'postcss-loader', options: { parser: 'sugarss', exec: true } }
  ]
}

`Config`

Name	Type	Default	Description
`path`	`{String}`	`undefined`	PostCSS Config Directory
`context`	`{Object}`	`undefined`	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, this option only allows you to manually specify the directory where config lookup should start from

webpack.config.js

{
  loader: 'postcss-loader',
  options: {
    config: {
      path: 'path/to/.config/' ✅
      path: 'path/to/.config/css.config.js' ❌
    }
  }
}

`Context (ctx)`

Name	Type	Default	Description
`env`	`{String}`	`'development'`	`process.env.NODE_ENV`
`file`	`{Object}`	`loader.resourcePath`	`extname`, `dirname`, `basename`
`options`	`{Object}`	`{}`	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

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
  }
})

webpack.config.js

{
  loader: 'postcss-loader',
  options: {
    config: {
      ctx: {
        'postcss-preset-env': {...options},
        cssnano: {...options},
      }
    }
  }
}

`Plugins`

webpack.config.js

{
  loader: 'postcss-loader',
  options: {
    ident: 'postcss',
    plugins: (loader) => [
      require('postcss-import')({ root: loader.resourcePath }),
      require('postcss-preset-env')(),
      require('cssnano')()
    ]
  }
}

⚠️ 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
`parser`	`{String\\|Function}`	`undefined`	Custom PostCSS Parser
`syntax`	`{String\\|Function}`	`undefined`	Custom PostCSS Syntax
`stringifier`	`{String\\|Function}`	`undefined`	Custom PostCSS Stringifier

`Parser`

webpack.config.js

{
  test: /\.sss$/,
  use: [
    ...,
    { loader: 'postcss-loader', options: { parser: 'sugarss' } }
  ]
}

`Syntax`

webpack.config.js

{
  test: /\.css$/,
  use: [
    ...,
    { loader: 'postcss-loader', options: { syntax: 'sugarss' } }
  ]
}

`Stringifier`

webpack.config.js

{
  test: /\.css$/,
  use: [
    ...,
    { loader: 'postcss-loader', options: { stringifier: 'midas' } }
  ]
}

`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

{
  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 } }
  ]
}

`'inline'`

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

webpack.config.js

{
  loader: 'postcss-loader',
  options: {
    sourceMap: 'inline'
  }
}

.class { color: red; }
 
/*# sourceMappingURL=data:application/json;base64, ... */

Examples

`Stylelint`

webpack.config.js

{
  test: /\.css$/,
  use: [
    'style-loader',
    'css-loader',
    {
      loader: 'postcss-loader',
      options: {
        ident: 'postcss',
        plugins: [
          require('postcss-import')(),
          require('stylelint')(),
          ...,
        ]
      }
    }
  ]
}

`Autoprefixing`

webpack.config.js

{
  test: /\.css$/,
  use: [
    'style-loader',
    'css-loader',
    {
      loader: 'postcss-loader',
      options: {
        ident: 'postcss',
        plugins: [
          require('autoprefixer')({...options}),
          ...,
        ]
      }
    }
  ]
}

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

{
  test: /\.css$/,
  use: [
    'style-loader',
    { loader: 'css-loader', options: { modules: true, importLoaders: 1 } },
    'postcss-loader'
  ]
}

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

{
  test: /\.style.js$/,
  use: [
    'style-loader',
    { loader: 'css-loader', options: { importLoaders: 2 } },
    { loader: 'postcss-loader', options: { parser: 'postcss-js' } },
    'babel-loader'
  ]
}

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

import colors from './styles/colors'
 
export default {
    '.menu': {
      color: colors.main,
      height: 25,
      '&_link': {
      color: 'white'
    }
  }
}

⚠️ If you are using Babel you need to do the following in order for the setup to work

Add babel-plugin-add-module-exports to your configuration

You need to have only one default export per style module

Extract CSS

webpack.config.js

const devMode = process.env.NODE_ENV !== 'production'
 
const MiniCssExtractPlugin = require('mini-css-extract-plugin')
 
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          devMode ? 'style-loader' : MiniCssExtractPlugin.loader,
          'css-loader',
          'postcss-loader'
        ]
      }
    ]
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: devMode ? '[name].css' : '[name].[hash].css'
    })
  ]
}

Maintainers

Michael Ciniawsky

Alexander Krasnoyarov

Keywords

install

npm i postcss-loader

weekly downloads

2,116,568

version

3.0.0

license

MIT

homepage

github.com

repository

github

last publish

a month ago

collaborators

Test with RunKit

Report a vulnerability

postcss-loader

PostCSS Loader

Install

Usage

Configuration

Config Cascade

Options

Exec

Config

Path

Context (ctx)

Plugins

Syntaxes

Parser

Syntax

Stringifier

SourceMap

'inline'

Examples

Stylelint

Autoprefixing

CSS Modules

CSS-in-JS

Extract CSS

Maintainers

Keywords

install

Downloadsweekly downloads

version

license

homepage

repository

last publish

collaborators

`Configuration`

`Config Cascade`

`Exec`

`Config`

`Path`

`Context (ctx)`

`Plugins`

`Syntaxes`

`Parser`

`Syntax`

`Stringifier`

`SourceMap`

`'inline'`

`Stylelint`

`Autoprefixing`

`CSS Modules`

`CSS-in-JS`

weekly downloads