Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/postcss/postcss-load-config
Autoload Config for PostCSS
https://github.com/postcss/postcss-load-config
Last synced: 5 days ago
JSON representation
Autoload Config for PostCSS
- Host: GitHub
- URL: https://github.com/postcss/postcss-load-config
- Owner: postcss
- License: mit
- Created: 2016-05-30T18:40:38.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-06-04T10:26:32.000Z (8 months ago)
- Last Synced: 2025-01-07T08:08:07.792Z (12 days ago)
- Language: JavaScript
- Homepage:
- Size: 961 KB
- Stars: 649
- Watchers: 16
- Forks: 73
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-github-star - postcss-load-config
README
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
### `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`
```
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](https://www.npmjs.com/package/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](https://www.npmjs.com/package/tsx) or [jiti](https://www.npmjs.com/package/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`**](#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'
}
```
Plugins
### `{} || 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]
}
}
```
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
Michael Ciniawsky
Mateusz Derks
Contributors
