README

# 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

### <tt>package.json</tt>

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

Project (Root)
|– client
|– public
|
|- package.json
{
"postcss": {
"parser": "sugarss",
"map": false,
"plugins": {
"postcss-plugin": {}
}
}
}

### <tt>.postcssrc</tt>

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`**

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

**`.postcssrc.yml`**

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

### <tt>.postcssrc.js</tt> or <tt>postcss.config.js</tt>

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**

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**

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

#### <tt>{Object}</tt>

**.postcssrc.js**

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

#### <tt>{Array}</tt>

**.postcssrc.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

### <tt>parser</tt>

**.postcssrc.js**

module.exports = {
parser: 'sugarss'
}

### <tt>syntax</tt>

**.postcssrc.js**

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

### <tt>stringifier</tt>

**.postcssrc.js**

module.exports = {
stringifier: 'midas'
}

### <a href="https://github.com/postcss/postcss/blob/master/docs/source-maps.md">**<tt>map</tt>**</a>

**.postcssrc.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

### <tt>to</tt>

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

### <tt>from</tt>

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

## Plugins

### <tt>{} || null</tt>

The plugin will be loaded with defaults

'postcss-plugin': {} || null

**.postcssrc.js**

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

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

### <tt>{Object}</tt>

The plugin will be loaded with given options

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

**.postcssrc.js**

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

### <tt>false</tt>

The plugin will not be loaded

'postcss-plugin': false

**.postcssrc.js**

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

### <tt>Ordering</tt>

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

### <tt>Async</tt>

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

### <tt>Sync</tt>

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

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

## Maintainers

Michael Ciniawsky

Mateusz Derks <tbody>

## Contributors

Ryan Dunckel

Patrick Gilday

Dalton Santos <tbody>