Install

1npm i -D postcss-load-config

Usage

1npm 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

1{
2  "postcss": {
3    "parser": "sugarss",
4    "map": false,
5    "plugins": {
6      "postcss-plugin": {}
7    }
8  }
9}

.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

1{
2  "parser": "sugarss",
3  "map": false,
4  "plugins": {
5    "postcss-plugin": {}
6  }
7}

.postcssrc.yml

1parser: sugarss
2map: false
3plugins:
4  postcss-plugin: {}

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

.postcssrc.js or postcss.config.js

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

1module.exports = {
2  parser: 'sugarss',
3  map: false,
4  plugins: {
5    'postcss-plugin': {}
6  }
7}

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

.postcssrc.js

1module.exports = (ctx) => ({
2  parser: ctx.parser ? 'sugarss' : false,
3  map: ctx.env === 'development' ? ctx.map : false,
4  plugins: {
5    'postcss-plugin': ctx.options.plugin
6  }
7})

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

{Object}

.postcssrc.js

1module.exports = ({ env }) => ({
2  ...options,
3  plugins: {
4    'postcss-plugin': env === 'production' ? {} : false
5  }
6})

ℹ️ 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

1module.exports = ({ env }) => ({
2  ...options,
3  plugins: [
4    env === 'production' ? require('postcss-plugin')() : false
5  ]
6})

: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

1module.exports = {
2  parser: 'sugarss'
3}

syntax

.postcssrc.js

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

stringifier

.postcssrc.js

1module.exports = {
2  stringifier: 'midas'
3}

map

.postcssrc.js

1module.exports = {
2  map: 'inline'
3}

: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

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

from

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

Plugins

{} || null

The plugin will be loaded with defaults

1'postcss-plugin': {} || null

.postcssrc.js

1module.exports = {
2  plugins: {
3    'postcss-plugin': {} || null
4  }
5}

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

{Object}

The plugin will be loaded with given options

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

.postcssrc.js

1module.exports = {
2  plugins: {
3    'postcss-plugin': { option: '', option: '' }
4  }
5}

false

The plugin will not be loaded

1'postcss-plugin': false

.postcssrc.js

1module.exports = {
2  plugins: {
3    'postcss-plugin': false
4  }
5}

Ordering

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

1{
2  plugins: {
3    'postcss-plugin': {}, // [0]
4    'postcss-plugin': {}, // [1]
5    'postcss-plugin': {}  // [2]
6  }
7}

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

1module.exports = (ctx) => ({
2  parser: ctx.parser ? 'sugarss' : false,
3  map: ctx.env === 'development' ? ctx.map : false,
4  plugins: {
5    'postcss-import': {},
6    'postcss-nested': {},
7    cssnano: ctx.env === 'production' ? {} : false
8  }
9})

1"scripts": {
2  "build": "NODE_ENV=production node postcss",
3  "start": "NODE_ENV=development node postcss"
4}

1const { readFileSync } = require('fs')
2
3const postcss = require('postcss')
4const postcssrc = require('postcss-load-config')
5
6const css = readFileSync('index.css', 'utf8')
7
8const ctx = { parser: true, map: 'inline' }
9
10postcssrc(ctx).then(({ plugins, options }) => {
11  postcss(plugins)
12    .process(css, options)
13    .then((result) => console.log(result.css))
14})

1"scripts": {
2  "build": "NODE_ENV=production gulp",
3  "start": "NODE_ENV=development gulp"
4}

1const { task, src, dest, series, watch } = require('gulp')
2
3const postcss = require('gulp-postcssrc')
4
5const css = () => {
6  src('src/*.css')
7    .pipe(postcss())
8    .pipe(dest('dest'))
9})
10
11task('watch', () => {
12  watch(['src/*.css', 'postcss.config.js'], css)
13})
14
15task('default', series(css, 'watch'))

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

webpack.config.js

1module.exports = (env) => ({
2  module: {
3    rules: [
4      {
5        test: /\.css$/,
6        use: [
7          'style-loader',
8          'css-loader',
9          'postcss-loader'
10        ]
11      }
12    ]
13  }
14})

Maintainers

Michael Ciniawsky

Mateusz Derks

Contributors

Security Contact

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

Ryan Dunckel

Patrick Gilday

Dalton Santos

François Wouts