Install

npm i -D postcss-load-config

Usage

npm i -S|-D postcss-plugin

Install plugins and save them to your package.json dependencies/devDependencies.

package.json

Create postcss section in your projects package.json.

App
  |– client
  |– public
  |
  |- package.json

{
  "postcss": {
    "parser": "sugarss",
    "map": false,
    "from": "/path/to/src.sss",
    "to": "/path/to/dest.css",
    "plugins": {
      "postcss-plugin": {}
    }
  }
}

.postcssrc

Create a .postcssrc file in JSON or YAML format.

It's also allowed to use extensions (.postcssrc.json or .postcssrc.yaml). That could help your text editor to properly interpret the file.

App
  |– client
  |– public
  |
  |- (.postcssrc|.postcssrc.json|.postcssrc.yaml)
  |- package.json

JSON

{
  "parser": "sugarss",
  "map": false,
  "from": "/path/to/src.sss",
  "to": "/path/to/dest.css",
  "plugins": {
    "postcss-plugin": {}
  }
}

YAML

parser: sugarss
map: false
from: "/path/to/src.sss"
to: "/path/to/dest.css"
plugins:
  postcss-plugin: {}

postcss.config.js or .postcssrc.js

You may need some JavaScript logic to generate your config. For this case you can use a file named postcss.config.js or .postcssrc.js.

App
  |– client
  |– public
  |
  |- (postcss.config.js|.postcssrc.js)
  |- package.json

You can export the config as an {Object}

module.exports = {
  parser: 'sugarss',
  map: false,
  from: '/path/to/src.sss',
  to: '/path/to/dest.css',
  plugins: {
    'postcss-plugin': {}
  }
}

Or export a {Function} that returns the config (more about the param ctx below)

module.exports = (ctx) => ({
  parser: ctx.parser ? 'sugarss' : false,
  map: ctx.env === 'development' ? ctx.map : false,
  from: ctx.from,
  to: ctx.to,
  plugins: {
    'postcss-plugin': ctx.plugin
  }
})

Plugins can be loaded in either using an {Object} or an {Array}.

{Object}

module.exports = (ctx) => ({
  ...options
  plugins: {
    'postcss-plugin': ctx.plugin
  }
})

{Array}

module.exports = (ctx) => ({
  ...options
  plugins: [
    require('postcss-plugin')(ctx.plugin)
  ]
})

⚠ When using an Array, make sure to require() them.

Options

parser:

'parser': 'sugarss'

syntax:

'syntax': 'postcss-scss'

stringifier:

'stringifier': 'midas'

map:

'map': 'inline'

from:

from: 'path/to/src.css'

to:

to: 'path/to/dest.css'

Plugins

Options

{} || null: Plugin loads with defaults.

'postcss-plugin': {} || null

⚠ {} must be an empty object

[Object]: Plugin loads with given options.

'postcss-plugin': { option: '', option: '' }

false: Plugin will not be loaded.

'postcss-plugin': false

Order

Plugin order is determined by declaration in the plugins section.

{
  plugins: {
    'postcss-plugin': {}, // plugins[0]
    'postcss-plugin': {}, // plugins[1]
    'postcss-plugin': {}  // plugins[2]
  }
}

Context

When using a function (postcss.config.js or .postcssrc.js), it is possible to pass context to postcss-load-config, which will be evaluated while loading your config. By default ctx.env (process.env.NODE_ENV) and ctx.cwd (process.cwd()) are available.

Examples

postcss.config.js

module.exports = (ctx) => ({
  parser: ctx.parser ? 'sugarss' : false,
  map: ctx.env === 'development' ? ctx.map : false,
  plugins: {
    'postcss-import': {},
    'postcss-nested': {},
    cssnano: ctx.env === 'production' ? {} : false
  }
})

"scripts": {
  "build": "NODE_ENV=production node postcss",
  "start": "NODE_ENV=development node postcss"
}

const { readFileSync } = require('fs')

const postcss = require('postcss')
const postcssrc = require('postcss-load-config')

const css = readFileSync('index.sss', 'utf8')

const ctx = { parser: true, map: 'inline' }

postcssrc(ctx).then(({ plugins, options }) => {
  postcss(plugins)
    .process(css, options)
    .then((result) => console.log(result.css))
})

"scripts": {
  "build": "NODE_ENV=production gulp",
  "start": "NODE_ENV=development gulp"
}

const { task, src, dest, series, watch } = require('gulp')

const postcss = require('gulp-postcssrc')

const css = () => {
  src('src/*.css')
    .pipe(postcss())
    .pipe(dest('dest'))
})

task('watch', () => {
  watch(['src/*.css', 'postcss.config.js'], css)
})

task('default', series(css, 'watch'))

"scripts": {
  "build": "NODE_ENV=production webpack",
  "start": "NODE_ENV=development webpack-dev-server"
}

module.exports = (env) => ({
  module: {
    rules: [
      {
        test: /\.css$/
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: { importLoaders: 1 } }
          },
          'postcss-loader'
        ]
      }
    ]
  }
})

Maintainers

Michael Ciniawsky

Mateusz Derks

Contributors

Ryan Dunckel

Patrick Gilday

Dalton Santos