postcss-loader

What is postcss-loader?

The postcss-loader npm package is a loader for webpack that allows you to use PostCSS to process CSS with JavaScript. It enables the use of PostCSS plugins to perform various operations on CSS files, such as autoprefixing, minification, and custom transformations.

What are postcss-loader's main functionalities?

Autoprefixing

Automatically adds vendor prefixes to CSS rules using values from Can I Use. It is useful for supporting multiple browser versions.

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  require('autoprefixer')
                ]
              }
            }
          }
        ]
      }
    ]
  }
};

CSS Minification

Optimizes and minifies CSS files to reduce file size and improve load times.

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  require('cssnano')()
                ]
              }
            }
          }
        ]
      }
    ]
  }
};

Custom Transformations

Applies custom transformations or future CSS features using PostCSS plugins.

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  require('postcss-custom-properties')()
                ]
              }
            }
          }
        ]
      }
    ]
  }
};

Other packages similar to postcss-loader

sass-loader

The sass-loader compiles Sass/SCSS files to CSS. It requires Node.js-style .sass/.scss files. Unlike postcss-loader, it's specifically designed for Sass pre-processing.

less-loader

The less-loader processes .less files and compiles them to CSS. It's similar to postcss-loader in that it transforms styles, but it's tailored for the Less pre-processor.

stylus-loader

This package is a webpack loader that compiles Stylus files to CSS. It's a pre-processor loader like sass-loader and less-loader, but for Stylus syntax.

README

PostCSS for Webpack

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

Usage

Install postcss-loader:

npm install postcss-loader --save-dev

Set postcss section in webpack config:

var precss       = require('precss');
var autoprefixer = require('autoprefixer');

module.exports = {
    module: {
        loaders: [
            {
                test:   /\.css$/,
                loader: "style-loader!css-loader!postcss-loader"
            }
        ]
    },
    postcss: function () {
        return [precss, autoprefixer];
    }
}

This example implementation uses two plugins that may need to be installed:

npm install precss --save-dev
npm install autoprefixer --save-dev

Now your CSS files requirements will be processed by selected PostCSS plugins:

var css = require('./file.css');
// => CSS after PreCSS and Autoprefixer

Note that the context of this function

module.exports = {
    ...
    postcss: function () {
        return [autoprefixer, precss];
    }
}

will be set to the webpack loader-context. If there is the need, this will let you access to webpack loaders API.

Source Maps

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: {
        loader: "style-loader!css-loader!postcss-loader?sourceMap=inline"
    }
}

Plugins Packs

If you want to process different styles by different PostCSS plugins you can define plugin packs in postcss section and use them by ?pack=name parameter.

module.exports = {
    module: {
        loaders: [
            {
                test:   /\.docs\.css$/,
                loader: "style-loader!css-loader!postcss-loader?pack=cleaner"
            },
            {
                test:   /\.css$/,
                loader: "style-loader!css-loader!postcss-loader"
            }
        ]
    },
    postcss: function () {
        return {
            defaults: [precss, autoprefixer],
            cleaner:  [autoprefixer({ browsers: [] })]
        };
    }
}

Custom 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.

For example, you can use Safe Parser to find and fix any CSS errors:

var css = require('postcss?parser=postcss-safe-parser!./broken')

If you need to pass the function directly instead of a module name, you can do so through the webpack postcss option, as such:

var sugarss = require('sugarss')
module.exports = {
    module: {
        loaders: [
            {
                test:   /\.css$/,
                loader: "style-loader!css-loader!postcss-loader"
            }
        ]
    },
    postcss: function () {
        return {
            plugins: [autoprefixer, precss],
            syntax: sugarss
        };
    }
}

Examples

With postcss-import

When using postcss-import plugin, you may want to tell webpack about dependencies coming from your @import directives. For example: in watch mode, to enable recompile on change.

Here is a simple way to let know postcss-import to pass files to webpack:

var postcssImport = require('postcss-import');

module.exports = {
    module: {
        loaders: [
            {
                test:   /\.css$/,
                loader: "style-loader!css-loader!postcss-loader"
            }
        ]
    },
    postcss: function (webpack) {
        return [
            postcssImport({
                addDependencyTo: webpack
            })
        ];
    }
}

With CSS Modules

postcss-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$/,
    loader: "style-loader!css-loader?modules&importLoaders=1!postcss-loader"
}

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

Custom 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.

For example, you can use Safe Parser to find and fix any CSS errors:

var css = require('postcss?parser=postcss-safe-parser!./broken')

If you need to pass the function directly instead of a module name, you can do so through the webpack postcss option, as such:

var sugarss = require('sugarss')
module.exports = {
    module: {
        loaders: [
            {
                test:   /\.css$/,
                loader: "style-loader!css-loader!postcss-loader"
            }
        ]
    },
    postcss: function () {
        return {
            plugins: [autoprefixer, precss],
            syntax: sugarss
        };
    }
}

JS Styles

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

{
    test:   /\.style.js$/,
    loader: "style-loader!css-loader!postcss-loader?parser=postcss-js"
}

Or use can use even ES6 in JS styles by Babel:

{
    test:   /\.style.js$/,
    loader: "style-loader!css-loader!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'
        }
    }
}

Webpack Events

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

See the example implementation.

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