From 8f55703e219ca9267c96af0d474458f835623983 Mon Sep 17 00:00:00 2001 From: Michael Ciniawsky Date: Thu, 9 Feb 2017 01:23:05 +0100 Subject: [PATCH 1/3] chore(package): add engines --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index 40b2cca..e426a95 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,7 @@ "version": "2.6.0", "description": "CLI for PostCSS", "main": "index.js", + "engines": { "node": ">=4" }, "bin": { "postcss": "./bin/postcss" }, From f2de62d28491fdffaa29a8e4eed1b26c8d10a983 Mon Sep 17 00:00:00 2001 From: Michael Ciniawsky Date: Thu, 9 Feb 2017 01:23:48 +0100 Subject: [PATCH 2/3] ci(appveyor): add platform tests --- appveyor.yml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 appveyor.yml diff --git a/appveyor.yml b/appveyor.yml new file mode 100644 index 0000000..2f9467a --- /dev/null +++ b/appveyor.yml @@ -0,0 +1,18 @@ +environment: + matrix: + - nodejs_version: "7" + - nodejs_version: "6" + - nodejs_version: "4" + +version: "{build}" +build: off +deploy: off + +install: + - ps: Install-Product node $env:nodejs_version + - npm install + +test_script: + - node --version + - npm --version + - npm test From 09cc5fc6467e0f07a83c0408b037bcbe59153a66 Mon Sep 17 00:00:00 2001 From: Michael Ciniawsky Date: Thu, 9 Feb 2017 01:24:20 +0100 Subject: [PATCH 3/3] docs(README): add ctx docs --- README.md | 128 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 86 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index bd4354a..e0022f4 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ +[![npm][npm]][npm-url] +[![node][node]][node-url] +[![deps][deps]][deps-url] [![tests][tests]][tests-url] [![cover][cover]][cover-url] -[![deps][deps]][deps-url] -[![npm][npm]][npm-url] [![code style][style]][style-url] [![chat][chat]][chat-url] @@ -13,72 +14,115 @@

PostCSS CLI

-## Installation +

Install

```bash -npm i -D postcss-cli +npm i -g|-D postcss-cli ``` -## Usage +

Usage

+```bash +postcss [input.css] [OPTIONS] [-o|--output output.css] [-w|--watch] ``` -postcss [input.css] [OPTIONS] [--output|-o output.css] [--watch] - -Options: - -o, --output Output file [string] - -d, --dir Output directory [string] - -r, --replace Replace (overwrite) the input file [boolean] - -u, --use List of postcss plugins to use [array] - -p, --parser Custom postcss parser [string] - -t, --stringifier Custom postcss stringifier [string] - -s, --syntax Custom postcss syntax [string] - -w, --watch Watch files for changes and recompile as needed [boolean] - -x, --extension Override the output file extension [string] - -e, --env A shortcut for setting NODE_ENV [string] - -c, --config Set a custom path to look for a config file [string] - -m, --map Create an external sourcemap - --no-map Disable the default inline sourcemaps - -h, --help Show help [boolean] - -v, --version Show version number [boolean] - -Examples: - postcss input.css -o output.css Basic usage - cat input.css | postcss -u Piping input & output - autoprefixer > output.css - -If no input files are passed, it reads from stdin. If neither -o, --dir, or ---replace is passed, it writes to stdout. -If there are multiple input files, the --dir or --replace option must be passed. +> ⚠️ If there are multiple input files, the --dir or --replace option must be passed. + +```bash +cat input.css | postcss [OPTIONS] > output.css ``` -For more details on custom parsers, stringifiers and syntaxes, see the [postcss docs](https://github.com/postcss/postcss#syntaxes). +> ⚠️ If no input files are passed, it reads from stdin. If neither -o, --dir, or +--replace is passed, it writes to stdout. + +

Options

+ +|Name|Type|Default|Description| +|:---|:--:|:-----:|:----------| +|`-d, --dir`|`{String}`|`undefined`|Output Directory| +|`-o, --output`|`{String}`|`undefined`|Output File| +|`-r, --replace`|`{String}`|`undefined`|Input <=> Output| +|`-x, --extension`|`{String}`|`extname(output)`|Output File Extension| +|`-p, --parser`|`{String}`|`undefined`|Custom PostCSS Parser| +|`-s, --syntax`|`{String}`|`undefined`|Custom PostCSS Syntax| +|`-s, --stringifier`|`{String}`|`undefined`|Custom PostCSS Stringifier| +|`-u, --use`|`{Array}`|`[]`|List of PostCSS Plugins| +|`-m, --map`|`{Boolean}`|`{ inline: true }`|External Sourcemap| +|`--no-map`|`{Boolean}`|`false`|Disable Sourcemaps| +|`-e, --env`|`{String}`|`process.env.NODE_ENV`|Shortcut for setting `$NODE_ENV`| +|`-c, --config`|`{String}`|`dirname(file)`|Path to `postcss.config.js`| +|`-h, --help`|`{Boolean}`|`false`|CLI Help| +|`-v, --version`|`{Boolean}`|`false`|CLI Version| + -## Configuration +> ℹ️ More details on custom parsers, stringifiers and syntaxes, can be found [here](https://github.com/postcss/postcss#syntaxes). + +### [Config](https://github.com/michael-ciniawsky/postcss-load-config) If you need to pass options to your plugins, or have a long plugin chain, you'll want to use a configuration file. -Example `postcss.config.js`: +**postcss.config.js** ```js -module.exports = () => { +module.exports = { parser: 'sugarss', plugins: [ - require('postcss-import')({ /* Options */ }), - require('postcss-url')({ - url: 'copy', - useHash: true - }) + require('postcss-import')({...options}), + require('postcss-url')({ url: 'copy', useHash: true }) ] } ``` -Configuration files are handled by [postcss-load-config](https://github.com/michael-ciniawsky/postcss-load-config). Refer to the docs there for more details. +### Context + +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** + +|Name|Type|Default|Description| +|:--:|:--:|:-----:|:----------| +|`env`|`{String}`|`'development'`|process.env.NODE_ENV| +|`file`|`{Object}`|`dirname, basename, extname`|File| +|`options`|`{Object}`|`map, parser, syntax, stringifier`|PostCSS Options| + +**postcss.config.js** + +```js +module.exports = (ctx) => ({ + map: ctx.options.map, + parser: ctx.file.extname === '.sss' ? 'sugarss' : false, + plugins: { + 'postcss-import': { root: ctx.file.dirname }), + 'cssnano': ctx.env === 'production' ? {} : false + } +}) +``` + +> ⚠️ If you want to set options via CLI, it's mandatory to reference `ctx.options` in `postcss.config.js` + + +```bash +postcss input.sss -p sugarss -o output.css -m +``` + +**postcss.config.js** + +```js +module.exports = (ctx) => ({ + map: ctx.options.map, + parser: ctx.options.parser, + plugins: { + 'postcss-import': { root: ctx.file.dirname }), + 'cssnano': ctx.env === 'production' ? {} : false + } +}) +``` [npm]: https://img.shields.io/npm/v/postcss-cli.svg [npm-url]: https://npmjs.com/package/postcss-cli +[node]: https://img.shields.io/node/v/posthtml-loader.svg +[node-url]: https://nodejs.org/ + [deps]: https://img.shields.io/gemnasium/postcss/postcss-cli.svg [deps-url]: https://gemnasium.com/postcss/postcss-cli