Migrating from v2 to v3

--use and input file placement

In v2, if you wanted to process your files with autoprefixer and cssnano, you could do:

postcss --use autoprefixer --use cssnano css/*.css -d dist/

In v3, you can pass multiple plugins to --use. However, you must list your input files first. The same command in v3:

postcss css/*.css -d dist/ --use postcss-cssnext autoprefixer

Config files

If you do not use a config file in v2, and you:

• Pass options to plugins using the --plugin.key=value syntax, or
• Use --local-plugins

you will need to use a config file in v3.

If you used a config file in v2, you will need to migrate it to the v3 format.

v3 uses https://github.com/michael-ciniawsky/postcss-load-config to load and parse the config files; complete docs may be found there. Here is a quick overview:

Your config file must be named postcss.config.js (you can also use a .postcssrc file, or add your config to the package.json; that will not be covered here).

If you are currently using a JSON config file, we recommend switching to a JS config.

Config Migration Example

Example v2 config:

module.exports = {
  parser: 'sugarss',
  use: ['postcss-import', 'postcss-cssnext', 'cssnano'],
  cssnano: {
    autoprefixer: false
  }
}

Migrating that to v3:

There are two ways to structure your v3 plugins; an array or an object.

{Array}

module.exports = {
  parser: 'sugarss',
  plugins: [
    require('postcss-import')(),
    require('postcss-cssnext')(),
    require('cssnano')({
      autoprefixer: false
    })
  ]
}

{Object}

module.exports = {
  parser: 'sugarss',
  plugins: {
    'postcss-import': {},
    'postcss-cssnext': {},
    cssnano: {
      autoprefixer: false
    }
  }
}

You can also export a function that will receive a context parameter, like this:

module.exports = function (ctx) {
  return {
    parser: ctx.file.extname === '.sss' ? 'sugarss' : null,
    plugins: [
      require('postcss-import')(),
      require('postcss-cssnext')(),
      require('cssnano')({
        autoprefixer: false
      })
    ]
  }
}

More info on context: https://github.com/postcss/postcss-cli#context