node package manager

postcss-cli

CLI for PostCSS

npm node deps tests cover code style chat

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
-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
  }
})