Skip to content

webpack/postcss-loader

BranchesTags

Repository files navigation

npm node deps tests coverage chat

PostCSS Logo

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 before css-loader and style-loader, but after other preprocessor loaders like e.g sass|less|stylus-loader, if you use any (since webpack loaders evaluate right to left/bottom to top).

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|Function} undefined Set PostCSS Parser
syntax {String|Object} undefined Set PostCSS Syntax
stringifier {String|Object|Function} undefined Set PostCSS Stringifier
config {String|Object|Boolean} undefined Set postcss.config.js config path && ctx
plugins {Function|Object|Array<Function|Object>} [] Set PostCSS Plugins
sourceMap {String|Boolean} compiler.devtool Enables/Disables generation of source maps

Exec

Type: Boolean Default: undefined

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

webpack.config.js

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

Config

Type: Boolean|String|Object Default: undefined

Options specified in the config file are combined with options passed to the loader. Loader options overwrite options from config.

Boolean

Enables/Disables autoloading config.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'postcss-loader',
        options: {
          config: false,
        },
      },
    ],
  },
};

String

Allows to specify the absolute path to the config file.

webpack.config.js

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

Object

Name Type Default Description
path {String} undefined PostCSS Config Directory
context {Object} undefined PostCSS Config Context
Path

Type: String Default: undefined

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'postcss-loader',
        options: {
          config: {
            path: 'path/to/.config/', // ✅
            path: 'path/to/.config/css.config.js', // ❌
          },
        },
      },
    ],
  },
};
Context (ctx)

Type: Object Default: undefined

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'postcss-loader',
        options: {
          config: {
            ctx: {
              'postcss-preset-env': { ...options },
              cssnano: { ...options },
            },
          },
        },
      },
    ],
  },
};

Plugins

Type: Function|Object|Array<Function\|Object> Default: []

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'postcss-loader',
        options: {
          plugins: (loader) => [
            require('postcss-import')({ root: loader.resourcePath }),
            require('postcss-preset-env')(),
            require('cssnano')(),
          ],
        },
      },
    ],
  },
};

webpack.config.js

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

It is possible to disable the plugin specified in the config.

postcss.config.js

module.exports = {
  plugins: {
    'postcss-short': { prefix: 'x' },
    'postcss-import': {},
    'postcss-nested': {},
  },
};

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'postcss-loader',
        options: {
          plugins: {
            'postcss-import': {},
            'postcss-nested': {},
            // Turn off the plugin
            'postcss-short': false,
          },
        },
      },
    ],
  },
};

Syntaxes

Type: String|Object Default: undefined

Name Type Default Description
parser {String|Object} undefined Custom PostCSS Parser
syntax {String|Object} undefined Custom PostCSS Syntax
stringifier {String|Object|Function} undefined Custom PostCSS Stringifier

Parser

Type: String|Object|Function Default: undefined

String

The passed string is converted to the form require('string').

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: 'postcss-loader',
        options: {
          // Will be converted to `require('sugarss')`
          parser: 'sugarss',
        },
      },
    ],
  },
};
Object

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: 'postcss-loader',
        options: {
          parser: require('sugarss'),
        },
      },
    ],
  },
};
Function

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: 'postcss-loader',
        options: {
          parser: require('sugarss').parse,
        },
      },
    ],
  },
};

Syntax

Type: String|Object Default: undefined

String

The passed string is converted to the form require('string').

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'postcss-loader',
        options: {
          // Will be converted to `require('sugarss')`
          syntax: 'sugarss',
        },
      },
    ],
  },
};
Object

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'postcss-loader',
        options: {
          stringifier: require('sugarss'),
        },
      },
    ],
  },
};

Stringifier

Type: String|Object|Function Default: undefined

String

The passed string is converted to the form require('string').

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'postcss-loader',
        options: {
          // Will be converted to `require('sugarss')`
          stringifier: 'sugarss',
        },
      },
    ],
  },
};
Object

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'postcss-loader',
        options: {
          stringifier: require('sugarss'),
        },
      },
    ],
  },
};
Function

webpack.config.js

const Midas = require('midas');
const midas = new Midas();

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'postcss-loader',
        options: {
          stringifier: midas.stringifier,
        },
      },
    ],
  },
};

SourceMap

Type: Boolean|String Default: compiler.devtool

By default generation of source maps depends on the devtool option. All values enable source map generation except eval and false value. In most cases this option should be discouraged. If need postcss-loader to generate an inline map, use the inline value. 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

module.exports = {
  devtool: 'source-map',
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: 'style-loader', options: { sourceMap: true } },
          { loader: 'css-loader' },
          { loader: 'postcss-loader' },
          { loader: 'sass-loader' },
        ],
      },
    ],
  },
};

'inline'

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

webpack.config.js

module.exports = {
  devtool: 'source-map',
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: 'style-loader', options: { sourceMap: true } },
          { loader: 'css-loader' },
          { loader: 'postcss-loader', options: { sourceMap: 'inline' } },
          { loader: 'sass-loader' },
        ],
      },
    ],
  },
};
.class {
  color: red;
}

/*# sourceMappingURL=data:application/json;base64, ... */

Examples

Stylelint

webpack.config.js

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

Autoprefixing

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              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

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        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

module.exports = {
  module: {
    rules: [
      {
        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

  1. Add babel-plugin-add-module-exports to your configuration
  2. 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',
    }),
  ],
};

Emit assets

To write a asset from the postcss plugin to the webpack's output file system, need to add a message in result.messages. The message should contain the following fields:

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

webpack.config.js

const customPlugin = () => (css, result) => {
  result.messages.push({
    type: 'asset',
    file: 'sprite.svg',
    content: '<svg>...</svg>',
  });
};

const postcssPlugin = postcss.plugin('postcss-assets', customPlugin);

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

Add dependencies

There are two way to add dependencies:

  1. (Recommended). Postcss plugin should emit message in result.messages.

The message should contain the following fields:

  • type = dependency - Message type (require, should be equal dependency)
  • file - absolute file path (require)

webpack.config.js

const path = require('path');

const customPlugin = () => (css, result) => {
  result.messages.push({
    type: 'dependency',
    file: path.resolve(__dirname, 'path', 'to', 'file'),
  });
};

const postcssPlugin = postcss.plugin('postcss-assets', customPlugin);

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              plugins: [postcssPlugin()],
            },
          },
        ],
      },
    ],
  },
};
  1. Pass loaderContext in plugin.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              config: 'path/to/postcss.config.js',
            },
          },
        ],
      },
    ],
  },
};

postcss.config.js

module.exports = (loaderContext) => ({
  plugins: [require('path/to/customPlugin')(loaderContext)],
});

customPlugin.js

const path = require('path');

const customPlugin = (loaderContext) => (css, result) => {
  loaderContext.webpack.addDependency(
    path.resolve(__dirname, 'path', 'to', 'file')
  );
};

module.exports = postcss.plugin('postcss-assets', customPlugin);

Maintainers


Michael Ciniawsky
Alexander Krasnoyarov

About

PostCSS loader for webpack

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

2.8k stars

Watchers

44 watching

Forks

208 forks
Report repository

Releases 54

v8.2.0 Latest
Sep 1, 2025
+ 53 releases

Sponsor this project

Packages

No packages published

Contributors 84
+ 70 contributors

Languages