jescalan/postcss-loader

PostCSS loader for webpack

PostCSS for Webpack

PostCSS loader for webpack to postprocesses your CSS with PostCSS plugins.

Install

npm install postcss-loader --save-dev

Usage

Create postcss.config.js:

module.exports = {
  plugins: [
    require('postcss-smart-import')({ /* ...options */ }),
    require('precss')({ /* ...options */ }),
    require('autoprefixer')({ /* ...options */ })
  ]
}

You could put different configs in different directories. For example, global config in project/postcss.config.js and override its plugins in project/src/legacy/postcss.config.js.

You can read more about common PostCSS config in postcss-load-config.

Add PostCSS Loader to webpack.config.js. Put it after css-loader and style-loader. But before sass-loader, if you use it.

Webpack 2

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

Webpack 1

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

Options

Plugins

We recommend to use postcss.config.js, but also you can specify plugins directly in webpack config.

Webpack 2

module.exports = {
  module: {
    rules: [
      {
        test: /\.css/,
        use: [
          …
          {
            loader: 'postcss-loader',
            options: {
              plugins: function () {
                return [
                  require('precss'),
                  require('autoprefixer')
                ];
              }
            }
          }
        ]
      }
    ]
  }
}

Webpack 1

module.exports = {
  module: {
    loaders: [
      {
        test: /\.css$/,
        loaders: [
          …
          'postcss-loader'
        ]
      }
    ]
  },
  postcss: () => {
    return [
      require('precss'),
      require('autoprefixer')
    ];
  }
}

Syntaxes

PostCSS can transforms styles in any syntax, not only in CSS. There are 3 parameters to control syntax:

• syntax accepts module name with parse and stringify function.
• parser accepts module name with input parser function.
• stringifier accepts module name with output stringifier function.

module.exports = {
  module: {
    loaders: [
      {
        test:   /\.sss/,
        loaders: [
          'style-loader',
          'css-loader?importLoaders=1',
          'postcss-loader?parser=sugarss'
        ]
      }
    ]
  }
}

SourceMaps

Loader will use source map settings from previous loader.

You can set this sourceMap parameter to inline value to put source maps into CSS annotation comment:

module.exports = {
  module: {
    loaders: [
      {
        test: '\/.css',
        loaders: [
          'style-loader',
          'css-loader?importLoaders=1',
          'postcss-loader?sourceMap=inline'
        ]
      }
    ]
  }
}

Examples

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

…
      {
        test: /\.css$/,
        loaders: [
          'style-loader',
          'css-loader?modules&importLoaders=1',
          'postcss-loader'
        ]
      }
…

or use postcss-modules plugin instead of css-loader.

JS Styles

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

…
      {
        test: /\.style.js$/,
        loaders: [
          'style-loader',
          'css-loader?modules&importLoaders=1',
          'postcss-loader?parser=postcss-js',
          'babel'
        ]
      }
…

As result you will be able to write styles as:

import colors from './config/colors'

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

If you are using Babel >= v6 you need to do the following in order for the setup to work

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

If you use JS styles without postcss-js parser, you can add exec parameter:

…
      {
        test:   /\.style.xyz$/,
        loaders: [
          'style-loader',
          'css-loader?modules&importLoaders=1',
          'postcss-loader?parser=custom-parser&exec'
        ]
      }
…

Dynamic Config

PostCSS loader sends a loaded instance to PostCSS common config. You can use it to do some real magic:

module.exports = function (ctx) {
    if (check(ctx.webpack.resourcePath)) {
        return { plugins: plugins1 };
    } else {
        return { plugins: plugins2 };
    }
}

Webpack Events

Webpack provides webpack plugin developers a convenient way to hook into the build pipeline. The postcss-loader makes use of this event system to allow building integrated postcss-webpack tools.

See the example implementation.

Event postcss-loader-before-processing is fired before processing and allows to add or remove postcss plugins.