Skip to content

Commit 96194b6

Browse files
jsimckjsimck
authored
Update README.md
1 parent 8a129a7 commit 96194b6

1 file changed

Lines changed: 93 additions & 58 deletions

File tree

‎README.md‎

Lines changed: 93 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -6,87 +6,122 @@
66
<a href="https://github.com/jsimck/postcss-webpack-plugin/actions/workflows/ci.yml">
77
<img alt="ci" src="https://github.com/jsimck/postcss-webpack-plugin/actions/workflows/ci.yml/badge.svg?branch=main">
88
</a>
9-
<a href="https://conventionalcommits.org">
10-
<img alt="Conventional Commits" src="https://img.shields.io/badge/ Conventional%20Commits-1.0.0-yellow.svg">
11-
</a>
129
<a href="https://github.com/prettier/prettier">
1310
<img alt="Prettier" src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square">
1411
</a>
1512
</p>
1613

17-
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.
14+
Serves as an alternative and also addition to `postcss-loader`. While webpack loaders are pretty efficient, they allow you to process just one file at time.
15+
16+
This plugin tries to solve this issue while taking great inspiration from [postcss-pipeline-webpack-plugin](https://github.com/mistakster/postcss-pipeline-webpack-plugin#readme). It allows you to run PostCSS plugins on generated (and newly emitted) assets, with support for webpack 5.x filesystem cache and ability to change content of existing assets, rather than a need to always generate new ones.
1817

19-
## Quick start
18+
## Installation
2019
```console
21-
npx jsconfig.json
20+
npm i -D postcss-webpack-plugin
2221
```
2322

24-
By default the `jsconfig.json` is generated in **current working directory** (this is also where the script looks for existence of `webpack.config.js` or `package.json` file in order to try to extract path aliases).
25-
26-
This can be changed by providing path to custom working directory as a **first argument** of the cli (`npx jsconfig.json ~/Workspace/my-project`).
27-
28-
### Templates
29-
30-
There are few predefined jsconfig.json templates, that can be selected using `-t, --template` argument to help bootstrap the correct environment (`default` [default option], `nextjs`, `react`, `vuejs` and `node`).
31-
32-
```console
33-
npx jsconfig.json --template=nextjs
23+
## Usage
24+
25+
```javascript
26+
// webpack.config.js
27+
const { PostCSSWebpackPlugin } = require('postcss-webpack-plugin');
28+
29+
module.exports = {
30+
entry: 'base.css',
31+
plugins: [
32+
new MiniCssExtractPlugin({
33+
filename: '[name].css',
34+
chunkFilename: '[id].[name].css',
35+
}),
36+
...(config?.plugins ?? []),
37+
],
38+
module: {
39+
rules: [
40+
{
41+
test: /.css$/i,
42+
use: [MiniCssExtractPlugin.loader, 'css-loader'],
43+
},
44+
],
45+
},
46+
plugins: [
47+
new PostCSSWebpackPlugin({
48+
plugins: [require('postcss-pxtorem'), require('cssnano')],
49+
}),
50+
],
51+
};
3452
```
3553
36-
### Additional CLI options
54+
### Chaining multiple instances together
55+
56+
Following example first runs css nano and pxtorem plugin son the `base.css` asset and then creates a new one with only mobile styles (using `unmq` plugin) in the second pass.
57+
58+
```javascript
59+
// webpack.config.js
60+
const { PostCSSWebpackPlugin } = require('postcss-webpack-plugin');
61+
62+
module.exports = {
63+
// ...
64+
plugins: [
65+
new PostCSSWebpackPlugin({
66+
plugins: [require('postcss-pxtorem'), require('cssnano')],
67+
}),
68+
new PostCSSWebpackPlugin({
69+
plugins: [
70+
require('postcss-unmq')({
71+
type: 'screen',
72+
width: 540,
73+
}),
74+
],
75+
filename: '[name].mobile[ext]',
76+
})
77+
]
78+
}
79+
```
3780
38-
These allow you to further overwrite additional defaults or even provide custom `--baseUrl` and `--webpackConfigPath` that are used to generate correct paths to aliases. Lastly `--output` is used to define custom output directory for generated jsconfig.json file (this will not change the path aliases generation in any way). For more options run:
3981
40-
```console
41-
npx jsconfig.json --help
82+
### Plugin options
83+
```typescript
84+
interface PostCSSWebpackPluginOptions {
85+
filename?: string | ((filename: string) => string);
86+
filter?: RegExp | ((filename: string) => boolean);
87+
implementation?: Postcss;
88+
additionalAssets?: true | undefined;
89+
stage?: number;
90+
plugins: any[];
91+
}
4292
```
4393
44-
```console
45-
Usage: npx jsconfig.json <srcPath> [options]
46-
47-
Options:
48-
--help Show help [boolean]
49-
--version Show version number [boolean]
50-
-o, --output Optional custom output directory for generated jsconfig.json
51-
file [string]
52-
-t, --template Base jsconfig.json template
53-
[choices: "default", "nextjs", "react", "vuejs", "node"] [default: "default"]
54-
-b, --baseUrl Custom base url used for paths generation [string]
55-
-c, --webpackConfig Custom path to webpack.config.js [string]
56-
-a, --target Specifies which default library (lib.d.ts) to use
57-
[string] [choices: "es3", "es5", "es6", "es2015", "es2016", "es2017", "es2018", "es2019",
58-
"es2020", "esnext"] [default: "es2020"]
59-
-m, --module Specifies the module system, when generating module code
60-
[string] [choices: "amd", "commonJS", "es2015", "es6", "esnext", "none", "system", "umd"]
61-
[default: "es2015"]
62-
-r, --moduleResolution Specifies how modules are resolved for imports
63-
[string] [choices: "node", "classic"] [default: "node"]
64-
-e, --experimentalDecorators Enables experimental support for proposed ES decorators
65-
[boolean]
66-
-s, --syntheticImports Allow default imports from modules with no default export.
67-
This does not affect code emit, just type checking. [boolean]
68-
```
94+
#### `filename`
95+
> `string | ((filename: string) => string)`
6996
70-
### Support
71-
- Node.js >= **12.x**
97+
Optional custom filename. If not provided the plugins are applied on the existing css assets without creating new ones. Can be either function or string with support for `[base], [dir], [ext], [name], [root]` template variables.
7298
99+
#### `filter`
100+
> `RegExp | ((filename: string) => boolean)`
73101
74-
## Contributions
102+
Custom function or RegExp to filter assets to process (defaults to `/\.css$/`).
75103
76-
Contributions of any kind are very welcome!
104+
#### `implementation`
105+
> `Postcss`
77106
78-
This repository uses **conventional commits** in order to correctly generate CHANGELOG and release automatically. This means that all commits should follow correct form defined in the conventional commits specification. To make this process easier (and since there's pre-commit hook to validate commit messages. which won't let you commit invalid messages) you can run commit wizard using:
107+
Optional custom implementation for `postcss`. Can be usefull in some projects where the default `require('postcss')` resolves to wrong version.
79108
80-
```
81-
npm run commit
82-
```
109+
#### `additionalAssets`
110+
> `true | undefined`
111+
112+
Set to true to run plugin for newly emitted assets. Should be used in combination with `filter` option in order to prevent cycles in compilation.
83113
84-
Which will take you through the process of generating correct format of the commit message.
114+
#### `stage`
115+
> `number`
85116
86-
### Development
117+
Custom plugin processAssets hook stage (defaults to `PROCESS_ASSETS_STAGE_OPTIMIZE`).
87118
88-
To run cli in development you can use `npm run dev` to fires up nodemon which watches changes over the source files. By default the result is written to tmp/jsconfig.json when using nodemon (this looks int the root directory of the repository for webpack configs, you can provide custom webpack config while developing using CLI options `npm run dev -- --webpackConfig=/tmp/custom.webpack.test.config.js`).
119+
#### `plugins`
120+
> `any[]`
89121
90-
### Tests
122+
Array of postcss plugins.
91123
92-
Tests are written using [jest framework](https://jestjs.io/). To run them use either `npm run test` or `npm run test:unit`, `npm run test e2e` to run each set of tests separately.
124+
## Supported versions
125+
- node => 14
126+
- postcss => 8
127+
- webpack => 5

0 commit comments

Comments
 (0)