Elep

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![test][test]][test-url]
[![coverage][cover]][cover-url]
[![code style][style]][style-url]
[![chat][chat]][chat-url]

<div align="center">
  <img width="100" height="100" title="Load Options" src="http://michael-ciniawsky.github.io/postcss-load-options/logo.svg">
  <a href="https://github.com/postcss/postcss">
    <img width="110" height="110" title="PostCSS"           src="http://postcss.github.io/postcss/logo.svg" hspace="10">
  </a>
  <img width="100" height="100" title="Load Plugins" src="http://michael-ciniawsky.github.io/postcss-load-plugins/logo.svg">
  <h1>Load Config</h1>
</div>

<h2 align="center">Install</h2>

```bash
npm i -D postcss-load-config
```

<h2 align="center">Usage</h2>

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

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

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

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

<h2 align="center">Options</h2>

|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|[**`to`**](#to)|`{String}`|`undefined`|Destination File Path|
|[**`map`**](#map)|`{String\|Object}`|`false`|Enable/Disable Source Maps|
|[**`from`**](#from)|`{String}`|`undefined`|Source File Path|
|[**`parser`**](#parser)|`{String\|Function}`|`false`|Custom PostCSS Parser|
|[**`syntax`**](#syntax)|`{String\|Function}`|`false`|Custom PostCSS Syntax|
|[**`stringifier`**](#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`**](https://github.com/postcss/postcss/blob/master/docs/source-maps.md)

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

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

### `from`

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

<h2 align="center">Plugins</h2>

### `{} || null`

The plugin will be loaded with defaults

```js
'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

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

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

### `false`

The plugin will not be loaded

```js
'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**)

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

<h2 align="center">Context</h2>

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`

<h2 align="center">Examples</h2>

**postcss.config.js**

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

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

### `Async`

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

```js
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)
```

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

```js
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'))
```

```json
"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'
        ]
      }
    ]
  }
})
```

<h2 align="center">Maintainers</h2>

<table>
  <tbody>
   <tr>
    <td align="center">
      <img width="150" height="150"
        src="https://github.com/michael-ciniawsky.png?v=3&s=150">
      <br />
      <a href="https://github.com/michael-ciniawsky">Michael Ciniawsky</a>
    </td>
    <td align="center">
      <img width="150" height="150"
        src="https://github.com/ertrzyiks.png?v=3&s=150">
      <br />
      <a href="https://github.com/ertrzyiks">Mateusz Derks</a>
    </td>
  </tr>
  <tbody>
</table>

<h2 align="center">Contributors</h2>

<table>
  <tbody>
   <tr>
    <td align="center">
      <img width="150" height="150"
        src="https://github.com/sparty02.png?v=3&s=150">
      <br />
      <a href="https://github.com/sparty02">Ryan Dunckel</a>
    </td>
    <td align="center">
      <img width="150" height="150"
        src="https://github.com/pcgilday.png?v=3&s=150">
      <br />
      <a href="https://github.com/pcgilday">Patrick Gilday</a>
    </td>
    <td align="center">
      <img width="150" height="150"
        src="https://github.com/daltones.png?v=3&s=150">
      <br />
      <a href="https://github.com/daltones">Dalton Santos</a>
    </td>
  </tr>
  <tbody>
</table>

[npm]: https://img.shields.io/npm/v/postcss-load-config.svg
[npm-url]: https://npmjs.com/package/postcss-load-config

[node]: https://img.shields.io/node/v/postcss-load-plugins.svg
[node-url]: https://nodejs.org/

[deps]: https://david-dm.org/michael-ciniawsky/postcss-load-config.svg
[deps-url]: https://david-dm.org/michael-ciniawsky/postcss-load-config

[test]: http://img.shields.io/travis/michael-ciniawsky/postcss-load-config.svg
[test-url]: https://travis-ci.org/michael-ciniawsky/postcss-load-config

[cover]: https://coveralls.io/repos/github/michael-ciniawsky/postcss-load-config/badge.svg
[cover-url]: https://coveralls.io/github/michael-ciniawsky/postcss-load-config

[style]: https://img.shields.io/badge/code%20style-standard-yellow.svg
[style-url]: http://standardjs.com/

[chat]: https://img.shields.io/gitter/room/postcss/postcss.svg
[chat-url]: https://gitter.im/postcss/postcss