Skip to content

Commit 10f70c9

Browse files
RyanZimRyanZim
authored
Merge pull request #86 from michael-ciniawsky/readme
2 parents a18d881 + 09cc5fc commit 10f70c9

File tree

3 files changed

+105
-42
lines changed

3 files changed

+105
-42
lines changed

‎README.md‎

Lines changed: 86 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
1+
[![npm][npm]][npm-url]
2+
[![node][node]][node-url]
3+
[![deps][deps]][deps-url]
14
[![tests][tests]][tests-url]
25
[![cover][cover]][cover-url]
3-
[![deps][deps]][deps-url]
4-
[![npm][npm]][npm-url]
56
[![code style][style]][style-url]
67
[![chat][chat]][chat-url]
78

@@ -13,72 +14,115 @@
1314
<h1>PostCSS CLI</h1>
1415
</div>
1516

16-
## Installation
17+
<h2 align="center">Install</h2>
1718

1819
```bash
19-
npm i -D postcss-cli
20+
npm i -g|-D postcss-cli
2021
```
2122

22-
## Usage
23+
<h2 align="center">Usage</h2>
2324

25+
```bash
26+
postcss [input.css] [OPTIONS] [-o|--output output.css] [-w|--watch]
2427
```
25-
postcss [input.css] [OPTIONS] [--output|-o output.css] [--watch]
26-
27-
Options:
28-
-o, --output Output file [string]
29-
-d, --dir Output directory [string]
30-
-r, --replace Replace (overwrite) the input file [boolean]
31-
-u, --use List of postcss plugins to use [array]
32-
-p, --parser Custom postcss parser [string]
33-
-t, --stringifier Custom postcss stringifier [string]
34-
-s, --syntax Custom postcss syntax [string]
35-
-w, --watch Watch files for changes and recompile as needed [boolean]
36-
-x, --extension Override the output file extension [string]
37-
-e, --env A shortcut for setting NODE_ENV [string]
38-
-c, --config Set a custom path to look for a config file [string]
39-
-m, --map Create an external sourcemap
40-
--no-map Disable the default inline sourcemaps
41-
-h, --help Show help [boolean]
42-
-v, --version Show version number [boolean]
43-
44-
Examples:
45-
postcss input.css -o output.css Basic usage
46-
cat input.css | postcss -u Piping input & output
47-
autoprefixer > output.css
48-
49-
If no input files are passed, it reads from stdin. If neither -o, --dir, or
50-
--replace is passed, it writes to stdout.
5128

52-
If there are multiple input files, the --dir or --replace option must be passed.
29+
> ⚠️ If there are multiple input files, the --dir or --replace option must be passed.
30+
31+
```bash
32+
cat input.css | postcss [OPTIONS] > output.css
5333
```
5434

55-
For more details on custom parsers, stringifiers and syntaxes, see the [postcss docs](https://github.com/postcss/postcss#syntaxes).
35+
> ⚠️ If no input files are passed, it reads from stdin. If neither -o, --dir, or
36+
--replace is passed, it writes to stdout.
37+
38+
<h2 align="center">Options</h2>
39+
40+
|Name|Type|Default|Description|
41+
|:---|:--:|:-----:|:----------|
42+
|`-d, --dir`|`{String}`|`undefined`|Output Directory|
43+
|`-o, --output`|`{String}`|`undefined`|Output File|
44+
|`-r, --replace`|`{String}`|`undefined`|Input <=> Output|
45+
|`-x, --extension`|`{String}`|`extname(output)`|Output File Extension|
46+
|`-p, --parser`|`{String}`|`undefined`|Custom PostCSS Parser|
47+
|`-s, --syntax`|`{String}`|`undefined`|Custom PostCSS Syntax|
48+
|`-s, --stringifier`|`{String}`|`undefined`|Custom PostCSS Stringifier|
49+
|`-u, --use`|`{Array}`|`[]`|List of PostCSS Plugins|
50+
|`-m, --map`|`{Boolean}`|`{ inline: true }`|External Sourcemap|
51+
|`--no-map`|`{Boolean}`|`false`|Disable Sourcemaps|
52+
|`-e, --env`|`{String}`|`process.env.NODE_ENV`|Shortcut for setting `$NODE_ENV`|
53+
|`-c, --config`|`{String}`|`dirname(file)`|Path to `postcss.config.js`|
54+
|`-h, --help`|`{Boolean}`|`false`|CLI Help|
55+
|`-v, --version`|`{Boolean}`|`false`|CLI Version|
56+
5657

57-
## Configuration
58+
> ℹ️ More details on custom parsers, stringifiers and syntaxes, can be found [here](https://github.com/postcss/postcss#syntaxes).
59+
60+
### [Config](https://github.com/michael-ciniawsky/postcss-load-config)
5861

5962
If you need to pass options to your plugins, or have a long plugin chain, you'll want to use a configuration file.
6063

61-
Example `postcss.config.js`:
64+
**postcss.config.js**
6265

6366
```js
64-
module.exports = () => {
67+
module.exports = {
6568
parser: 'sugarss',
6669
plugins: [
67-
require('postcss-import')({ /* Options */ }),
68-
require('postcss-url')({
69-
url: 'copy',
70-
useHash: true
71-
})
70+
require('postcss-import')({...options}),
71+
require('postcss-url')({ url: 'copy', useHash: true })
7272
]
7373
}
7474
```
7575

76-
Configuration files are handled by [postcss-load-config](https://github.com/michael-ciniawsky/postcss-load-config). Refer to the docs there for more details.
76+
### Context
77+
78+
For more advanced usage it's recommend to to use a function in `postcss.config.js`, this gives you access to the CLI context to dynamically apply options and plugins **per file**
79+
80+
|Name|Type|Default|Description|
81+
|:--:|:--:|:-----:|:----------|
82+
|`env`|`{String}`|`'development'`|process.env.NODE_ENV|
83+
|`file`|`{Object}`|`dirname, basename, extname`|File|
84+
|`options`|`{Object}`|`map, parser, syntax, stringifier`|PostCSS Options|
85+
86+
**postcss.config.js**
87+
88+
```js
89+
module.exports = (ctx) => ({
90+
map: ctx.options.map,
91+
parser: ctx.file.extname === '.sss' ? 'sugarss' : false,
92+
plugins: {
93+
'postcss-import': { root: ctx.file.dirname }),
94+
'cssnano': ctx.env === 'production' ? {} : false
95+
}
96+
})
97+
```
98+
99+
> ⚠️ If you want to set options via CLI, it's mandatory to reference `ctx.options` in `postcss.config.js`
100+
101+
102+
```bash
103+
postcss input.sss -p sugarss -o output.css -m
104+
```
105+
106+
**postcss.config.js**
107+
108+
```js
109+
module.exports = (ctx) => ({
110+
map: ctx.options.map,
111+
parser: ctx.options.parser,
112+
plugins: {
113+
'postcss-import': { root: ctx.file.dirname }),
114+
'cssnano': ctx.env === 'production' ? {} : false
115+
}
116+
})
117+
```
77118

78119

79120
[npm]: https://img.shields.io/npm/v/postcss-cli.svg
80121
[npm-url]: https://npmjs.com/package/postcss-cli
81122

123+
[node]: https://img.shields.io/node/v/posthtml-loader.svg
124+
[node-url]: https://nodejs.org/
125+
82126
[deps]: https://img.shields.io/gemnasium/postcss/postcss-cli.svg
83127
[deps-url]: https://gemnasium.com/postcss/postcss-cli
84128

‎appveyor.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
environment:
2+
matrix:
3+
- nodejs_version: "7"
4+
- nodejs_version: "6"
5+
- nodejs_version: "4"
6+
7+
version: "{build}"
8+
build: off
9+
deploy: off
10+
11+
install:
12+
- ps: Install-Product node $env:nodejs_version
13+
- npm install
14+
15+
test_script:
16+
- node --version
17+
- npm --version
18+
- npm test

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
"version": "2.6.0",
44
"description": "CLI for PostCSS",
55
"main": "index.js",
6+
"engines": { "node": ">=4" },
67
"bin": {
78
"postcss": "./bin/postcss"
89
},

0 commit comments

Comments
 (0)