postcss-pipeline-webpack-plugin

A webpack plugin to process generated assets with PostCSS pipeline.

Preface

Webpack loaders are pretty cool but limited to process and generate only one file at a time. If you are extracting critical CSS or media queries into separate files, you are no longer able to process these files. This plugin was made to solve this problem.

Install

npm install --save postcss-pipeline-webpack-plugin

Compatibility

It requires webpack 5.x to work.

For webpack 4.x use postcss-pipeline-webpack-plugin@5 package.

For webpack 3.x use postcss-pipeline-webpack-plugin@3 package.

The plugin is compatible with PostCSS 6.x, 7.x and 8.x branches.

Usage

1const postcss = require('postcss');
2const PostCssPipelineWebpackPlugin = require('postcss-pipeline-webpack-plugin');
3
4const pipelinePlugin = new PostCssPipelineWebpackPlugin({
5  processor: postcss([
6      // provide any PostCSS plugins here
7  ]),
8  // provide an optional function to filter out unwanted CSS
9  predicate: name => /foobar.css$/.test(name),
10  // provide an optional string attached to the beginning of a new file
11  prefix: 'critical',
12  // provide an optional string which will be using as a suffix for newly generated files
13  suffix: 'processed',
14  // or you can generate the name by yourself
15  transformName: name => 'critical-' + name,
16  // you can pass any relevant SourceMap options
17  // see https://github.com/postcss/postcss/blob/master/docs/source-maps.md
18  map: {}
19});

So, you can use this initialized instance of the plugin in webpack configuration later.

1module.exports = {
2  mode: 'production',
3
4  entry: './src/index.css',
5
6  output: {
7    path: path.resolve('./dest/'),
8    filename: '[name].js'
9  },
10
11  module: {
12    rules: [
13      {
14        test: /\.css$/,
15        use: [
16          MiniCssExtractPlugin.loader,
17          'css-loader'
18        ]
19      }
20    ]
21  },
22
23  plugins: [
24    new MiniCssExtractPlugin({
25      filename: 'styles.css'
26    }),
27    pipelinePlugin
28  ]
29};

Advanced techniques

For example, you may want to process your styles with postcss-critical-css plugin. It generates an additional file, which contains only styles between start- and stop-tags. You can’t use the optimization of generated styles before the plugin because minification removes all comments. So, you have to minify “all” and “critical” parts separately.

It’s pretty easy with postcss-pipeline-webpack-plugin. You can provide as many PostCSS pipelines as you need.

For the task, we need to set up two pipelines with one plugin in each other:

• postcss-critical-split
• postcss-csso

1const PostCssPipelineWebpackPlugin = require('postcss-pipeline-webpack-plugin');
2const MiniCssExtractPlugin = require('mini-css-extract-plugin');
3const postcss = require('postcss');
4const criticalSplit = require('postcss-critical-split');
5const csso = require('postcss-csso');
6
7module.exports = {
8  // ...
9  plugins: [
10    new MiniCssExtractPlugin({
11      filename: 'styles.css'
12    }),
13    new PostCssPipelineWebpackPlugin({
14      suffix: 'critical',
15      processor: postcss([
16        criticalSplit({
17          output: criticalSplit.output_types.CRITICAL_CSS
18        })
19      ])
20    }),
21    new PostCssPipelineWebpackPlugin({
22      suffix: 'min',
23      processor: postcss([
24        csso({
25          restructure: false
26        })
27      ]),
28      map: {
29        inline: false
30      }
31    })
32  ]
33};

1. Webpack extracts all CSS into:

1styles.css

2. PostCSS generates critical CSS into styles.critical.css. So, you get two files:

1styles.css
2styles.critical.css

3. PostCSS optimize both files with csso and create relevant SourceMaps for them:

1styles.css
2styles.critical.css
3styles.min.css
4styles.min.css.map
5styles.critical.min.css
6styles.critical.min.css.map

As you can see, webpack generates artifacts in one pass.

See full webpack.config.js for more details.

Change log

6.0.0

2020-12-24

• [breaking] made the plugin fully compatible with webpack v5

5.1.2

2019-08-02

• [minor] updated dependencies

5.1.1

2019-07-07

• [minor] updated version of the engines

5.1.0

2019-07-03

• [major] added transformName option to generate destination filenames

5.0.0

2019-03-09

• [breaking] pipeline option was replaced with processor to let the developer decide which version of the PostCSS to use
• [minor] improved examples and documentation

4.1.2

2019-03-09

• [minor] fixed semver incompatibility

4.1.1

2019-03-05

DEPRECATED

4.1.0

2018-07-30

• [major] added prefix option

4.0.0

2018-03-27

• [major] added webpack 4 support

3.1.0

2018-02-05

• [major] made the plugin compatible with filename’s template like [name].css?[contenthash]

3.0.1

2017-08-14

• [minor] upgraded webpack-sources module

3.0.0

2017-05-30

• [breaking] set minimal required node.js version to 4.7
• [breaking] upgraded PostCSS and other minor dependencies

2.0.0

2017-03-20

• [breaking] switched to webpack 2 and upgraded minor dependencies

1.2.0

2016-12-28

• [fix] added previously generated Source Maps

1.1.0

2016-12-27

• [feature] suffix can contain any falsy value to skip rename
• [fix] added module.exports to main file

1.0.0

2016-12-20

• initial release

License

ISC