Load Config

Install

npm i -D postcss-load-config

Usage

npm i -S|-D postcss-plugin

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

Then create a postcss config file by choosing one of the following formats

`package.json`

Create a postcss section in your project's package.json

Project (Root)
  |– client
  |– public
  |
  |- package.json

{
  "postcss": {
    "parser": "sugarss",
    "map": false,
    "plugins": {
      "postcss-plugin": {}
    }
  }
}

`.postcssrc`

Create a .postcssrc file in JSON or YAML format

ℹ️ It's recommended to use an extension (e.g .postcssrc.json or .postcssrc.yml) instead of .postcssrc

Project (Root)
  |– client
  |– public
  |
  |- (.postcssrc|.postcssrc.json|.postcssrc.yml)
  |- package.json

.postcssrc.json
json { "parser": "sugarss", "map": false, "plugins": { "postcss-plugin": {} } }

.postcssrc.yml
yaml parser: sugarss map: false plugins: postcss-plugin: {}

`.postcssrc.js` or `postcss.config.js`

You may need some logic within your config. In this case create JS file named .postcssrc.js or postcss.config.js

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

You can export the config as an {Object}

.postcssrc.js
js module.exports = { parser: 'sugarss', map: false, plugins: { 'postcss-plugin': {} } }

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

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

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

`{Object}`

.postcssrc.js
js module.exports = ({ env }) => ({ ...options plugins: { 'postcss-plugin': env === 'production' ? {} : false } })

`{Array}`

.postcssrc.js
js module.exports = ({ env }) => ({ ...options plugins: [ env === 'production' ? require('postcss-plugin')() : false ] })

:warning: When using an {Array}, make sure to require() each plugin

Options

Name	Type	Default	Description
`to`	`{String}`	`undefined`	Destination File Path
`map`	`{String\\|Object}`	`false`	Enable/Disable Source Maps
`from`	`{String}`	`undefined`	Source File Path
`parser`	`{String\\|Function}`	`false`	Custom PostCSS Parser
`syntax`	`{String\\|Function}`	`false`	Custom PostCSS Syntax
`stringifier`	`{String\\|Function}`	`false`	Custom PostCSS Stringifier

`parser`

.postcssrc.js
js module.exports = { parser: 'sugarss' }

`syntax`

.postcssrc.js
js module.exports = { syntax: 'postcss-scss' }

`stringifier`

.postcssrc.js
js module.exports = { stringifier: 'midas' }

`map`

.postcssrc.js
js module.exports = { map: 'inline' }

:warning: In most cases options.from && options.to are set by the third-party which integrates this package (CLI, gulp, webpack). It's unlikely one needs to set/use options.from && options.to within a config file. Unless you're a third-party plugin author using this module and its Node API directly dont't set options.from && options.to yourself

`to`

module.exports = {
  to: 'path/to/dest.css'
}

`from`

module.exports = {
  from: 'path/to/src.css'
}

Plugins

`{} || null`

The plugin will be loaded with defaults

'postcss-plugin': {} || null

.postcssrc.js
js module.exports = { plugins: { 'postcss-plugin': {} || null } }

:warning: {} must be an empty {Object} literal

`{Object}`

The plugin will be loaded with given options

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

.postcssrc.js
js module.exports = { plugins: { 'postcss-plugin': { option: '', option: '' } } }

`false`

The plugin will not be loaded

'postcss-plugin': false

.postcssrc.js
js module.exports = { plugins: { 'postcss-plugin': false } }

`Ordering`

Plugin execution order is determined by declaration in the plugins section (**top-down**)

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

Context

When using a {Function} (postcss.config.js or .postcssrc.js), it's 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 on the ctx {Object}

ℹ️ Most third-party integrations add additional properties to the ctx (e.g postcss-loader). Check the specific module's README for more information about what is available on the respective ctx

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

`Async`

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

`Sync`

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

const { plugins, options } = postcssrc.sync(ctx)

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

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