www.aleph1.co.uk Git - yaffs-website/blob - node_modules/postcss-load-config/README.md

   1 [![npm][npm]][npm-url]
   2 [![node][node]][node-url]
   3 [![deps][deps]][deps-url]
   4 [![tests][tests]][tests-url]
   5 [![coverage][cover]][cover-url]
   6 [![code style][style]][style-url]
   7 [![chat][chat]][chat-url]
   8
   9 <div align="center">
  10   <img width="100" height="100" title="Load Options" src="http://michael-ciniawsky.github.io/postcss-load-options/logo.svg">
  11   <a href="https://github.com/postcss/postcss">
  12     <img width="110" height="110" title="PostCSS"           src="http://postcss.github.io/postcss/logo.svg" hspace="10">
  13   </a>
  14   <img width="100" height="100" title="Load Plugins" src="http://michael-ciniawsky.github.io/postcss-load-plugins/logo.svg">
  15   <h1>Load Config</h1>
  16 </div>
  17
  18 <h2 align="center">Install</h2>
  19
  20 ```bash
  21 npm i -D postcss-load-config
  22 ```
  23
  24 <h2 align="center">Usage</h2>
  25
  26 ```
  27 npm i -S|-D postcss-plugin
  28 ```
  29
  30 Install plugins and save them to your ***package.json*** dependencies/devDependencies.
  31
  32 ### `package.json`
  33
  34 Create **`postcss`** section in your projects **`package.json`**.
  35
  36 ```
  37 App
  38   |– client
  39   |– public
  40   |
  41   |- package.json
  42 ```
  43
  44 ```json
  45 {
  46   "postcss": {
  47     "parser": "sugarss",
  48     "map": false,
  49     "from": "/path/to/src.sss",
  50     "to": "/path/to/dest.css",
  51     "plugins": {
  52       "postcss-plugin": {}
  53     }
  54   }
  55 }
  56 ```
  57
  58 ### `.postcssrc`
  59
  60 Create a **`.postcssrc`** file in JSON or YAML format.
  61
  62 It's also allowed to use extensions (**`.postcssrc.json`** or **`.postcssrc.yaml`**). That could help your text editor to properly interpret the file.
  63
  64 ```
  65 App
  66   |– client
  67   |– public
  68   |
  69   |- (.postcssrc|.postcssrc.json|.postcssrc.yaml)
  70   |- package.json
  71 ```
  72
  73 **`JSON`**
  74 ```json
  75 {
  76   "parser": "sugarss",
  77   "map": false,
  78   "from": "/path/to/src.sss",
  79   "to": "/path/to/dest.css",
  80   "plugins": {
  81     "postcss-plugin": {}
  82   }
  83 }
  84 ```
  85
  86 **`YAML`**
  87 ```yaml
  88 parser: sugarss
  89 map: false
  90 from: "/path/to/src.sss"
  91 to: "/path/to/dest.css"
  92 plugins:
  93   postcss-plugin: {}
  94 ```
  95
  96 ### `postcss.config.js` or `.postcssrc.js`
  97
  98 You may need some JavaScript logic to generate your config. For this case you can use a file named **`postcss.config.js`** or **`.postcssrc.js`**.
  99
 100 ```
 101 App
 102   |– client
 103   |– public
 104   |
 105   |- (postcss.config.js|.postcssrc.js)
 106   |- package.json
 107 ```
 108
 109 You can export the config as an `{Object}`
 110
 111 ```js
 112 module.exports = {
 113   parser: 'sugarss',
 114   map: false,
 115   from: '/path/to/src.sss',
 116   to: '/path/to/dest.css',
 117   plugins: {
 118     'postcss-plugin': {}
 119   }
 120 }
 121 ```
 122
 123 Or export a `{Function}` that returns the config (more about the param `ctx` below)
 124
 125 ```js
 126 module.exports = (ctx) => ({
 127   parser: ctx.parser ? 'sugarss' : false,
 128   map: ctx.env === 'development' ? ctx.map : false,
 129   from: ctx.from,
 130   to: ctx.to,
 131   plugins: {
 132     'postcss-plugin': ctx.plugin
 133   }
 134 })
 135 ```
 136
 137 Plugins can be loaded in either using an `{Object}` or an `{Array}`.
 138
 139 ##### `{Object}`
 140
 141 ```js
 142 module.exports = (ctx) => ({
 143   ...options
 144   plugins: {
 145     'postcss-plugin': ctx.plugin
 146   }
 147 })
 148 ```
 149
 150 ##### `{Array}`
 151
 152 ```js
 153 module.exports = (ctx) => ({
 154   ...options
 155   plugins: [
 156     require('postcss-plugin')(ctx.plugin)
 157   ]
 158 })
 159 ```
 160 > :warning: When using an Array, make sure to `require()` them.
 161
 162 <h2 align="center">Options</h2>
 163
 164 **`parser`**:
 165
 166 ```js
 167 'parser': 'sugarss'
 168 ```
 169
 170 **`syntax`**:
 171
 172 ```js
 173 'syntax': 'postcss-scss'
 174 ```
 175 **`stringifier`**:
 176
 177 ```js
 178 'stringifier': 'midas'
 179 ```
 180
 181 [**`map`**:](https://github.com/postcss/postcss/blob/master/docs/source-maps.md)
 182
 183 ```js
 184 'map': 'inline'
 185 ```
 186
 187 **`from`**:
 188
 189 ```js
 190 from: 'path/to/src.css'
 191 ```
 192
 193 **`to`**:
 194
 195 ```js
 196 to: 'path/to/dest.css'
 197 ```
 198
 199 <h2 align="center">Plugins</h2>
 200
 201 ### Options
 202
 203 **`{} || null`**: Plugin loads with defaults.
 204
 205 ```js
 206 'postcss-plugin': {} || null
 207 ```
 208 > :warning: `{}` must be an **empty** object
 209
 210 **`[Object]`**: Plugin loads with given options.
 211
 212 ```js
 213 'postcss-plugin': { option: '', option: '' }
 214 ```
 215
 216 **`false`**: Plugin will not be loaded.
 217
 218 ```js
 219 'postcss-plugin': false
 220 ```
 221
 222 ### Order
 223
 224 Plugin **order** is determined by declaration in the plugins section.
 225
 226 ```js
 227 {
 228   plugins: {
 229     'postcss-plugin': {}, // plugins[0]
 230     'postcss-plugin': {}, // plugins[1]
 231     'postcss-plugin': {}  // plugins[2]
 232   }
 233 }
 234 ```
 235
 236 <h2 align="center">Context</h2>
 237
 238 When using a function (`postcss.config.js` or `.postcssrc.js`), it is 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.
 239
 240 <h2 align="center">Examples</h2>
 241
 242 **postcss.config.js**
 243
 244 ```js
 245 module.exports = (ctx) => ({
 246   parser: ctx.parser ? 'sugarss' : false,
 247   map: ctx.env === 'development' ? ctx.map : false,
 248   plugins: {
 249     'postcss-import': {},
 250     'postcss-nested': {},
 251     cssnano: ctx.env === 'production' ? {} : false
 252   }
 253 })
 254 ```
 255
 256 ### <img width="80" height="80" src="https://worldvectorlogo.com/logos/nodejs-icon.svg">
 257
 258 ```json
 259 "scripts": {
 260   "build": "NODE_ENV=production node postcss",
 261   "start": "NODE_ENV=development node postcss"
 262 }
 263 ```
 264
 265 ```js
 266 const { readFileSync } = require('fs')
 267
 268 const postcss = require('postcss')
 269 const postcssrc = require('postcss-load-config')
 270
 271 const css = readFileSync('index.sss', 'utf8')
 272
 273 const ctx = { parser: true, map: 'inline' }
 274
 275 postcssrc(ctx).then(({ plugins, options }) => {
 276   postcss(plugins)
 277     .process(css, options)
 278     .then((result) => console.log(result.css))
 279 })
 280 ```
 281
 282 ### <img width="80" height="80" src="https://worldvectorlogo.com/logos/gulp.svg">
 283
 284 ```json
 285 "scripts": {
 286   "build": "NODE_ENV=production gulp",
 287   "start": "NODE_ENV=development gulp"
 288 }
 289 ```
 290
 291 ```js
 292 const { task, src, dest, series, watch } = require('gulp')
 293
 294 const postcss = require('gulp-postcssrc')
 295
 296 const css = () => {
 297   src('src/*.css')
 298     .pipe(postcss())
 299     .pipe(dest('dest'))
 300 })
 301
 302 task('watch', () => {
 303   watch(['src/*.css', 'postcss.config.js'], css)
 304 })
 305
 306 task('default', series(css, 'watch'))
 307 ```
 308
 309 ### <img width="80" height="80" src="https://worldvectorlogo.com/logos/webpack.svg">
 310
 311 ```json
 312 "scripts": {
 313   "build": "NODE_ENV=production webpack",
 314   "start": "NODE_ENV=development webpack-dev-server"
 315 }
 316 ```
 317
 318 ```js
 319 module.exports = (env) => ({
 320   module: {
 321     rules: [
 322       {
 323         test: /\.css$/
 324         use: [
 325           'style-loader',
 326           {
 327             loader: 'css-loader',
 328             options: { importLoaders: 1 } }
 329           },
 330           'postcss-loader'
 331         ]
 332       }
 333     ]
 334   }
 335 })
 336 ```
 337
 338 <h2 align="center">Maintainers</h2>
 339
 340 <table>
 341   <tbody>
 342    <tr>
 343     <td align="center">
 344       <img width="150 height="150"
 345         src="https://avatars.githubusercontent.com/u/5419992?v=3&s=150">
 346       <br />
 347       <a href="https://github.com/michael-ciniawsky">Michael Ciniawsky</a>
 348     </td>
 349     <td align="center">
 350       <img width="150 height="150"
 351         src="https://avatars.githubusercontent.com/u/2437969?v=3&s=150">
 352       <br />
 353       <a href="https://github.com/ertrzyiks">Mateusz Derks</a>
 354     </td>
 355   </tr>
 356   <tbody>
 357 </table>
 358
 359 <h2 align="center">Contributors</h2>
 360
 361 <table>
 362   <tbody>
 363    <tr>
 364     <td align="center">
 365       <img width="150" height="150"
 366         src="https://avatars.githubusercontent.com/u/1483538?v=3&s=150">
 367       <br />
 368       <a href="https://github.com/sparty02">Ryan Dunckel</a>
 369     </td>
 370     <td align="center">
 371       <img width="150" height="150"
 372         src="https://avatars.githubusercontent.com/u/6249643?v=3&s=150">
 373       <br />
 374       <a href="https://github.com/pcgilday">Patrick Gilday</a>
 375     </td>
 376     <td align="center">
 377       <img width="150" height="150"
 378         src="https://avatars.githubusercontent.com/u/5603632?v=3&s=150">
 379       <br />
 380       <a href="https://github.com/daltones">Dalton Santos</a>
 381     </td>
 382   </tr>
 383   <tbody>
 384 </table>
 385
 386 [npm]: https://img.shields.io/npm/v/postcss-load-config.svg
 387 [npm-url]: https://npmjs.com/package/postcss-load-config
 388
 389 [node]: https://img.shields.io/node/v/postcss-load-plugins.svg
 390 [node-url]: https://nodejs.org/
 391
 392 [deps]: https://david-dm.org/michael-ciniawsky/postcss-load-config.svg
 393 [deps-url]: https://david-dm.org/michael-ciniawsky/postcss-load-config
 394
 395 [style]: https://img.shields.io/badge/code%20style-standard-yellow.svg
 396 [style-url]: http://standardjs.com/
 397
 398 [tests]: http://img.shields.io/travis/michael-ciniawsky/postcss-load-config.svg
 399 [tests-url]: https://travis-ci.org/michael-ciniawsky/postcss-load-config
 400
 401 [cover]: https://coveralls.io/repos/github/michael-ciniawsky/postcss-load-config/badge.svg
 402 [cover-url]: https://coveralls.io/github/michael-ciniawsky/postcss-load-config
 403
 404 [chat]: https://img.shields.io/gitter/room/postcss/postcss.svg
 405 [chat-url]: https://gitter.im/postcss/postcss