Load Config

Install

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

Usage

`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

$3

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": {}
}
}
}
`

$3

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

> [!NOTE]
> For YAML configs, you must have yaml installed as a peer dependency.

$3

You may need some logic within your config.
In this case create JS/TS file named:
- .postcssrc.js
- .postcssrc.mjs
- .postcssrc.cjs
- .postcssrc.ts
- .postcssrc.mts
- .postcssrc.cts
- postcss.config.js
- postcss.config.mjs
- postcss.config.cjs
- postcss.config.ts
- postcss.config.mts
- postcss.config.cts

> [!NOTE]
> For TypeScript configs, you must have tsx or jiti installed as a peer dependency.

`
Project (Root)
|– client
|– public
|- (.postcssrc|postcss.config).(js|mjs|cjs|ts|mts|cts)
|- 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
}
})
`

> ℹ️ When using an {Object}, the key can be a Node.js module name, a path to a JavaScript file that is relative to the directory of the PostCSS config file, or an absolute path to a JavaScript file.

#### {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|

$3

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

$3

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

$3

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

$3

.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

$3

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

$3

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

Plugins

$3

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

$3

The plugin will be loaded with given options

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

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

$3

The plugin will not be loaded

`js
'postcss-plugin': false
`

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

$3

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

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

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

`js
const { readFileSync } = require('fs')

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

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

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

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





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

Maintainers

src="https://github.com/michael-ciniawsky.png?v=3&s=150"> Michael Ciniawsky

src="https://github.com/ertrzyiks.png?v=3&s=150"> Mateusz Derks

Contributors

Security Contact

To report a security vulnerability, please use the [Tidelift security contact].
Tidelift will coordinate the fix and disclosure.

[Tidelift security contact]: https://tidelift.com/security

src="https://github.com/sparty02.png?v=3&s=150"> Ryan Dunckel

src="https://github.com/pcgilday.png?v=3&s=150"> Patrick Gilday

src="https://github.com/daltones.png?v=3&s=150"> Dalton Santos

src="https://github.com/fwouts.png?v=3&s=150"> François Wouts