8881/postcss-cli

CLI for postcss

PostCSS CLI

Install

npm i -g|-D postcss-cli

Usage

postcss [input.css] [OPTIONS] [-o|--output output.css] [-w|--watch]

⚠️ If there are multiple input files, the --dir or --replace option must be passed.

cat input.css | postcss [OPTIONS] > output.css

⚠️ 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
-w, --watch	{Boolean}	false	Watch files for changes and recompile as needed
-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

ℹ️ More details on custom parsers, stringifiers and syntaxes, can be found here.

Config

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

postcss.config.js

module.exports = {
  parser: 'sugarss',
  plugins: [
    require('postcss-import')({...options}),
    require('postcss-url')({ url: 'copy', useHash: true })
  ]
}

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

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

postcss input.sss -p sugarss -o output.css -m

postcss.config.js

module.exports = (ctx) => ({
  map: ctx.options.map,
  parser: ctx.options.parser,
  plugins: {
    'postcss-import': { root: ctx.file.dirname },
    'cssnano': ctx.env === 'production' ? {} : false
  }
})