Install
npm i -D postcss-load-config copy
Usage
npm i -S | -D postcss-plugin copy
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 copy
{
"postcss" : {
"parser" : "sugarss" ,
"map" : false,
"plugins" : {
"postcss-plugin" : {}
}
}
} copy
.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 copy
.postcssrc.json
{
"parser" : "sugarss" ,
"map" : false,
"plugins" : {
"postcss-plugin" : {}
}
} copy
.postcssrc.yml
parser : sugarss
map : false
plugins :
postcss-plugin : {} copy
[!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 copy
You can export the config as an {Object}
.postcssrc.js
module . exports = {
parser: 'sugarss' ,
map: false ,
plugins: {
'postcss-plugin' : {}
}
} copy
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
}
}) copy
Plugins can be loaded either using an {Object} or an {Array}
{Object}
.postcssrc.js
module . exports = ({ env }) => ({
... options,
plugins: {
'postcss-plugin' : env === 'production' ? {} : false
}
}) copy
ℹ️ 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
module . exports = ({ env }) => ({
... options,
plugins: [
env === 'production' ? require ( 'postcss-plugin' )() : false
]
}) copy
:warning: When using an {Array}, make sure to require() each plugin
Options
Name Type Default Description to{String}undefinedDestination File Path map{String|Object}falseEnable/Disable Source Maps from{String}undefinedSource File Path
parser
.postcssrc.js
module . exports = {
parser: 'sugarss'
} copy
syntax
.postcssrc.js
module . exports = {
syntax: 'postcss-scss'
} copy
stringifier
.postcssrc.js
module . exports = {
stringifier: 'midas'
} copy
.postcssrc.js
module . exports = {
map: 'inline'
} copy
: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'
} copy
from
module . exports = {
from: 'path/to/src.css'
} copy
Plugins
{} || null
The plugin will be loaded with defaults
'postcss-plugin' : {} || null copy
.postcssrc.js
module . exports = {
plugins: {
'postcss-plugin' : {} || null
}
} copy
:warning: {} must be an empty {Object} literal
{Object}
The plugin will be loaded with given options
'postcss-plugin' : { option: '' , option: '' } copy
.postcssrc.js
module . exports = {
plugins: {
'postcss-plugin' : { option: '' , option: '' }
}
} copy
false
The plugin will not be loaded
'postcss-plugin' : false copy
.postcssrc.js
module . exports = {
plugins: {
'postcss-plugin' : false
}
} copy
Ordering
Plugin execution order is determined by declaration in the plugins section (top-down )
{
plugins : {
'postcss-plugin' : {}, // [0]
'postcss-plugin' : {}, // [1]
'postcss-plugin' : {} // [2]
}
} copy
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
}
}) copy
"scripts" : {
"build" : "NODE_ENV=production node postcss" ,
"start" : "NODE_ENV=development node postcss"
} copy
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))
})
"scripts" : {
"build" : "NODE_ENV=production gulp" ,
"start" : "NODE_ENV=development gulp"
} copy
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"
} copy
webpack.config.js
module . exports = (env) => ({
module: {
rules: [
{
test: /\.css$/ ,
use: [
'style-loader' ,
'css-loader' ,
'postcss-loader'
]
}
]
}
}) copy
Maintainers
Contributors
To report a security vulnerability, please use the Tidelift security contact .
Tidelift will coordinate the fix and disclosure.