giotramu/postcss-config

Flexible PostCSS config that combines useful plugins like Autoprefixer, CSSNano, SVGO, Inline SVG, Custom Media, etc. It offers granular control instead of postcss-preset-env.

PostCSS Config

⚠️ The project will no longer be updated, but I am here to help with any concerns.

Flexible PostCSS config that combines useful plugins like Autoprefixer, CSSNano, SVGO, Inline SVG, Custom Media, etc. It offers granular control instead of postcss-preset-env.

• PostCSS Config
  • Install
  • Usage
  • Standard config
  • Extend the config
    • Disable plugins
  • Options
  • Browsers support
  • Advanced usage
  • Acknowledgments
  • License

Install

Install the PostCSS config and save them to your package.json devDependencies:

npm add --save-dev @giotramu/postcss-config

Usage

Create a postcss.config.cjs file in the root of your project and grab the configuration from the node_modules folder like so:

module.exports = require('@giotramu/postcss-config')

Standard config

The config bundles together the following plugins:

• autoprefixer
• cssnano
• postcss-custom-media
• postcss-inline-svg
• postcss-reporter
• svgo

You can inspect the source code of the standard config.

Extend the config

Install all your favourite PostCSS plugins and save them to your package.json as devDependencies. Now you can extend the standard PostCSS config, but remember that the plugins execution order is top-down:

// postcss.config.cjs

module.exports = require('@giotramu/postcss-config/extends')([
  'postcss-utilities',
  'postcss-autoreset',
  'postcss-calc',
  [
    'postcss-custom-media',
    {
      importFrom: 'path/to/file.css'
    }
  ],
  ['autoprefixer', false],
  [
    'cssnano',
    {
      preset: [
        'default',
        {
          svgo: false
        }
      ]
    }
  ]
])

By design, the behaviour of the extends API is overwriting the existing array values completely rather than concatenating them.

Disable plugins

You can disable and not load a single or a bunch of plugins by setting them to false:

// postcss.config.cjs

// Disable a single plugin
module.exports = require('@giotramu/postcss-config/extends')([
  ['autoprefixer', false]
])

// Turn off multiple plugins
module.exports = require('@giotramu/postcss-config/extends')([
  ['postcss-custom-media', false],
  ['autoprefixer', false],
  ['cssnano', false]
])

Options

You can pass the following options:

Option	Type	Default
browsers	string[]	Browserslist
debug	boolean	false
sourceMap	boolean or 'inline'	undefined
syntax	PostCSS syntax interface	undefined

// postcss.config.cjs

const options = {
  debug: true,
  browsers: ['> 1%', 'IE 10'],
  sourceMap: 'inline'
}

// The standard way
module.exports = require('@giotramu/postcss-config')(options)

// With extends API
module.exports = require('@giotramu/postcss-config/extends')([...], options)

Browsers support

PostCSS config is dispatched with a default browserslist query, used by the cssnano and autoprefixer plugins:

last 2 versions
not ie <= 11
not op_mini all
not dead
not < 0.5%

You can change the query when you need. An example:

// postcss.config.cjs

const browsers = ['> 1%', 'IE 10']

// The standard way
module.exports = require('@giotramu/postcss-config')({ browsers })

// With extends API
module.exports = require('@giotramu/postcss-config/extends')(['Your plugin'], {
  browsers
})

Advanced usage

It's possible to pass a context and decide which configuration to load:

NODE_ENV=development npm run dev

// postcss.config.cjs

module.exports = ctx =>
  ctx.env === 'development'
    ? require('@giotramu/postcss-config/extends')(
        [
          ['autoprefixer', false],
          ['cssnano', false]
        ],
        { sourceMap: 'inline' }
      )
    : require('@giotramu/postcss-config')({ sourceMap: false })

Acknowledgments

Thanks to the following projects for their contributions:

• deepmerge

License

Apache License 2.0

postcss-config's Issues

cssnano z-index

Disable the rebase of the z-index values into cssnano advanced configuration.

cssnano z-index doc

new postcss plugins

Add the following postcss-plugins and update the README.md file:

Plugins:

• postcss-selector-not

PostCSS v8.x migration

Keep track of PostCSS plugins compatibility with the PostCSS v8:

Plugin	Status
@csstools/postcss-sass	Evaluated
autoprefixer	✔
cssnano	Pending
postcss-custom-media	Pending
postcss-inline-svg	Not evaluated yet
postcss-reporter	✔
postcss-scss	✔
postcss-selector-not	Pending

Use consola package

Use consola package instead of JavaScript console.log.