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

   1 # PostCSS [![Travis Build Status][travis-img]][travis] [![AppVeyor Build Status][appveyor-img]][appveyor] [![Gitter][chat-img]][chat]
   2
   3 <img align="right" width="95" height="95"
   4      title="Philosopher’s stone, logo of PostCSS"
   5      src="http://postcss.github.io/postcss/logo.svg">
   6
   7 [appveyor-img]: https://img.shields.io/appveyor/ci/ai/postcss.svg?label=windows
   8 [travis-img]:   https://img.shields.io/travis/postcss/postcss.svg?label=unix
   9 [chat-img]:     https://img.shields.io/badge/Gitter-Join_the_PostCSS_chat-brightgreen.svg
  10 [appveyor]:     https://ci.appveyor.com/project/ai/postcss
  11 [travis]:       https://travis-ci.org/postcss/postcss
  12 [chat]:         https://gitter.im/postcss/postcss
  13
  14 PostCSS is a tool for transforming styles with JS plugins.
  15 These plugins can lint your CSS, support variables and mixins,
  16 transpile future CSS syntax, inline images, and more.
  17
  18 PostCSS is used by industry leaders including Wikipedia, Twitter, Alibaba,
  19 and JetBrains. The [Autoprefixer] PostCSS plugin is one of the most popular
  20 CSS processors.
  21
  22 Twitter account:      [@postcss](https://twitter.com/postcss).
  23 VK.com page:          [postcss](https://vk.com/postcss).
  24 Support / Discussion: [Gitter](https://gitter.im/postcss/postcss).
  25
  26 For PostCSS commercial support (consulting, improving the front-end culture
  27 of your company, PostCSS plugins), contact [Evil Martians](https://evilmartians.com/?utm_source=postcss)
  28 at <surrender@evilmartians.com>.
  29
  30 [Autoprefixer]: https://github.com/postcss/autoprefixer
  31
  32 <a href="https://evilmartians.com/?utm_source=postcss">
  33   <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
  34        alt="Sponsored by Evil Martians" width="236" height="54">
  35 </a>
  36
  37 ## Plugins
  38
  39 Currently, PostCSS has more than 200 plugins. You can find all of the plugins
  40 in the [plugins list] or in the [searchable catalog]. Below is a list
  41 of our favorite plugins — the best demonstrations of what can be built
  42 on top of PostCSS.
  43
  44 If you have any new ideas, [PostCSS plugin development] is really easy.
  45
  46 [searchable catalog]: http://postcss.parts
  47 [plugins list]:       https://github.com/postcss/postcss/blob/master/docs/plugins.md
  48
  49 ### Solve Global CSS Problem
  50
  51 * [`postcss-use`] allows you to explicitly set PostCSS plugins within CSS
  52   and execute them only for the current file.
  53 * [`postcss-modules`] and [`react-css-modules`] automatically isolate
  54   selectors within components.
  55 * [`postcss-autoreset`] is an alternative to using a global reset
  56   that is better for isolatable components.
  57 * [`postcss-initial`] adds `all: initial` support, which resets
  58   all inherited styles.
  59 * [`cq-prolyfill`] adds container query support, allowing styles that respond
  60   to the width of the parent.
  61
  62 ### Use Future CSS, Today
  63
  64 * [`autoprefixer`] adds vendor prefixes, using data from Can I Use.
  65 * [`postcss-cssnext`] allows you to use future CSS features today
  66   (includes `autoprefixer`).
  67 * [`postcss-image-set-polyfill`] emulates [`image-set`] function logic for all browsers
  68
  69 ### Better CSS Readability
  70
  71 * [`precss`] contains plugins for Sass-like features, like variables, nesting,
  72   and mixins.
  73 * [`postcss-sorting`] sorts the content of rules and at-rules.
  74 * [`postcss-utilities`] includes the most commonly used shortcuts and helpers.
  75 * [`short`] adds and extends numerous shorthand properties.
  76
  77 ### Images and Fonts
  78
  79 * [`postcss-assets`] inserts image dimensions and inlines files.
  80 * [`postcss-sprites`] generates image sprites.
  81 * [`font-magician`] generates all the `@font-face` rules needed in CSS.
  82 * [`postcss-inline-svg`] allows you to inline SVG and customize its styles.
  83 * [`postcss-write-svg`] allows you to write simple SVG directly in your CSS.
  84
  85 ### Linters
  86
  87 * [`stylelint`] is a modular stylesheet linter.
  88 * [`stylefmt`] is a tool that automatically formats CSS
  89   according `stylelint` rules.
  90 * [`doiuse`] lints CSS for browser support, using data from Can I Use.
  91 * [`colorguard`] helps you maintain a consistent color palette.
  92
  93 ### Other
  94
  95 * [`postcss-rtl`] combines both-directional (left-to-right and right-to-left) styles in one CSS file.
  96 * [`cssnano`] is a modular CSS minifier.
  97 * [`lost`] is a feature-rich `calc()` grid system.
  98 * [`rtlcss`] mirrors styles for right-to-left locales.
  99
 100 [PostCSS plugin development]: https://github.com/postcss/postcss/blob/master/docs/writing-a-plugin.md
 101 [`postcss-inline-svg`]:       https://github.com/TrySound/postcss-inline-svg
 102 [`react-css-modules`]:        https://github.com/gajus/react-css-modules
 103 [`postcss-autoreset`]:        https://github.com/maximkoretskiy/postcss-autoreset
 104 [`postcss-write-svg`]:        https://github.com/jonathantneal/postcss-write-svg
 105 [`postcss-utilities`]: https://github.com/ismamz/postcss-utilities
 106 [`postcss-initial`]:          https://github.com/maximkoretskiy/postcss-initial
 107 [`postcss-sprites`]:          https://github.com/2createStudio/postcss-sprites
 108 [`postcss-modules`]:          https://github.com/outpunk/postcss-modules
 109 [`postcss-sorting`]:          https://github.com/hudochenkov/postcss-sorting
 110 [`postcss-cssnext`]:          http://cssnext.io
 111 [`postcss-image-set-polyfill`]: https://github.com/SuperOl3g/postcss-image-set-polyfill
 112 [`postcss-assets`]:           https://github.com/assetsjs/postcss-assets
 113 [`font-magician`]:            https://github.com/jonathantneal/postcss-font-magician
 114 [`autoprefixer`]:             https://github.com/postcss/autoprefixer
 115 [`cq-prolyfill`]:             https://github.com/ausi/cq-prolyfill
 116 [`postcss-rtl`]:              https://github.com/vkalinichev/postcss-rtl
 117 [`postcss-use`]:              https://github.com/postcss/postcss-use
 118 [`css-modules`]:              https://github.com/css-modules/css-modules
 119 [`colorguard`]:               https://github.com/SlexAxton/css-colorguard
 120 [`stylelint`]:                https://github.com/stylelint/stylelint
 121 [`stylefmt`]:                 https://github.com/morishitter/stylefmt
 122 [`cssnano`]:                  http://cssnano.co
 123 [`precss`]:                   https://github.com/jonathantneal/precss
 124 [`doiuse`]:                   https://github.com/anandthakker/doiuse
 125 [`rtlcss`]:                   https://github.com/MohammadYounes/rtlcss
 126 [`short`]:                    https://github.com/jonathantneal/postcss-short
 127 [`lost`]:                     https://github.com/peterramsing/lost
 128 [`image-set`]:                https://drafts.csswg.org/css-images-3/#image-set-notation
 129
 130 ## Syntaxes
 131
 132 PostCSS can transform styles in any syntax, not just CSS.
 133 If there is not yet support for your favorite syntax,
 134 you can write a parser and/or stringifier to extend PostCSS.
 135
 136 * [`sugarss`] is a indent-based syntax like Sass or Stylus.
 137 * [`postcss-scss`] allows you to work with SCSS
 138   *(but does not compile SCSS to CSS)*.
 139 * [`postcss-less`] allows you to work with Less
 140   *(but does not compile LESS to CSS)*.
 141 * [`postcss-less-engine`] allows you to work with Less
 142   *(and DOES compile LESS to CSS using true Less.js evaluation)*.
 143 * [`postcss-js`] allows you to write styles in JS or transform
 144   React Inline Styles, Radium or JSS.
 145 * [`postcss-safe-parser`] finds and fixes CSS syntax errors.
 146 * [`midas`] converts a CSS string to highlighted HTML.
 147
 148 [`postcss-safe-parser`]: https://github.com/postcss/postcss-safe-parser
 149 [`postcss-less`]:        https://github.com/webschik/postcss-less
 150 [`postcss-less-engine`]: https://github.com/Crunch/postcss-less
 151 [`postcss-scss`]:        https://github.com/postcss/postcss-scss
 152 [`postcss-js`]:          https://github.com/postcss/postcss-js
 153 [`sugarss`]:             https://github.com/postcss/sugarss
 154 [`midas`]:               https://github.com/ben-eb/midas
 155
 156 ## Articles
 157
 158 * [Some things you may think about PostCSS… and you might be wrong](http://julian.io/some-things-you-may-think-about-postcss-and-you-might-be-wrong)
 159 * [What PostCSS Really Is; What It Really Does](http://davidtheclark.com/its-time-for-everyone-to-learn-about-postcss)
 160 * [PostCSS Guides](http://webdesign.tutsplus.com/series/postcss-deep-dive--cms-889)
 161 * [Mastering PostCSS for Web Design](https://www.packtpub.com/web-development/mastering-postcss-web-design)
 162
 163 More articles and videos you can find on [awesome-postcss](https://github.com/jjaderg/awesome-postcss) list.
 164
 165 ## Usage
 166
 167 You can start using PostCSS in just two steps:
 168
 169 1. Find and add PostCSS extensions for your build tool.
 170 2. [Select plugins] and add them to your PostCSS process.
 171
 172 [Select plugins]: http://postcss.parts
 173
 174 ### Webpack
 175
 176 Use [`postcss-loader`] in `webpack.config.js`:
 177
 178 ```js
 179 module.exports = {
 180     module: {
 181         loaders: [
 182             {
 183                 test: /\.css$/,
 184                 loaders: [
 185                     'style-loader',
 186                     'css-loader?importLoaders=1',
 187                     'postcss-loader'
 188                 ]
 189             }
 190         ]
 191     }
 192 }
 193 ```
 194
 195 Then create `postcss.config.js`:
 196
 197 ```js
 198 module.exports = {
 199     plugins: [
 200         require('precss'),
 201         require('autoprefixer')
 202     ]
 203 }
 204 ```
 205
 206 [`postcss-loader`]: https://github.com/postcss/postcss-loader
 207
 208 ### Gulp
 209
 210 Use [`gulp-postcss`] and [`gulp-sourcemaps`].
 211
 212 ```js
 213 gulp.task('css', function () {
 214     var postcss    = require('gulp-postcss');
 215     var sourcemaps = require('gulp-sourcemaps');
 216
 217     return gulp.src('src/**/*.css')
 218         .pipe( sourcemaps.init() )
 219         .pipe( postcss([ require('precss'), require('autoprefixer') ]) )
 220         .pipe( sourcemaps.write('.') )
 221         .pipe( gulp.dest('build/') );
 222 });
 223 ```
 224
 225 [`gulp-sourcemaps`]: https://github.com/floridoo/gulp-sourcemaps
 226 [`gulp-postcss`]:    https://github.com/postcss/gulp-postcss
 227
 228 ### npm run / CLI
 229
 230 To use PostCSS from your command-line interface or with npm scripts
 231 there is [`postcss-cli`].
 232
 233 ```sh
 234 postcss --use autoprefixer -c options.json -o main.css css/*.css
 235 ```
 236
 237 [`postcss-cli`]: https://github.com/postcss/postcss-cli
 238
 239 ### Browser
 240
 241 If you want to compile CSS string in browser (for instance, in live edit
 242 tools like CodePen), just use [Browserify] or [webpack]. They will pack
 243 PostCSS and plugins files into a single file.
 244
 245 To apply PostCSS plugins to React Inline Styles, JSS, Radium
 246 and other CSS-in-JS, you can use [`postcss-js`] and transforms style objects.
 247
 248 ```js
 249 var postcss  = require('postcss-js');
 250 var prefixer = postcss.sync([ require('autoprefixer') ]);
 251
 252 prefixer({ display: 'flex' }); //=> { display: ['-webkit-box', '-webkit-flex', '-ms-flexbox', 'flex'] }
 253 ```
 254
 255 [`postcss-js`]: https://github.com/postcss/postcss-js
 256 [Browserify]:   http://browserify.org/
 257 [webpack]:      https://webpack.github.io/
 258
 259 ### Runners
 260
 261 * **Grunt**: [`grunt-postcss`](https://github.com/nDmitry/grunt-postcss)
 262 * **HTML**: [`posthtml-postcss`](https://github.com/posthtml/posthtml-postcss)
 263 * **Stylus**: [`poststylus`](https://github.com/seaneking/poststylus)
 264 * **Rollup**: [`rollup-plugin-postcss`](https://github.com/egoist/rollup-plugin-postcss)
 265 * **Brunch**: [`postcss-brunch`](https://github.com/brunch/postcss-brunch)
 266 * **Broccoli**: [`broccoli-postcss`](https://github.com/jeffjewiss/broccoli-postcss)
 267 * **Meteor**: [`postcss`](https://atmospherejs.com/juliancwirko/postcss)
 268 * **ENB**: [`enb-postcss`](https://github.com/awinogradov/enb-postcss)
 269 * **Fly**: [`fly-postcss`](https://github.com/postcss/fly-postcss)
 270 * **Start**: [`start-postcss`](https://github.com/start-runner/postcss)
 271 * **Connect/Express**: [`postcss-middleware`](https://github.com/jedmao/postcss-middleware)
 272
 273 ### JS API
 274
 275 For other environments, you can use the JS API:
 276
 277 ```js
 278 const postcss = require('postcss');
 279 const precss = require('precss');
 280 const autoprefixer = require('autoprefixer');
 281
 282 fs.readFile('src/app.css', (err, css) => {
 283     postcss([precss, autoprefixer])
 284         .process(css, { from: 'src/app.css', to: 'dest/app.css' })
 285         .then(result => {
 286             fs.writeFile('dest/app.css', result.css);
 287             if ( result.map ) fs.writeFile('dest/app.css.map', result.map);
 288         });
 289 });
 290 ```
 291
 292 Read the [PostCSS API documentation] for more details about the JS API.
 293
 294 All PostCSS runners should pass [PostCSS Runner Guidelines].
 295
 296 [PostCSS Runner Guidelines]: https://github.com/postcss/postcss/blob/master/docs/guidelines/runner.md
 297 [PostCSS API documentation]: http://api.postcss.org/postcss.html
 298
 299 ### Options
 300
 301 Most PostCSS runners accept two parameters:
 302
 303 * An array of plugins.
 304 * An object of options.
 305
 306 Common options:
 307
 308 * `syntax`: an object providing a syntax parser and a stringifier.
 309 * `parser`: a special syntax parser (for example, [SCSS]).
 310 * `stringifier`: a special syntax output generator (for example, [Midas]).
 311 * `map`: [source map options].
 312 * `from`: the input file name (most runners set it automatically).
 313 * `to`: the output file name (most runners set it automatically).
 314
 315 [source map options]: https://github.com/postcss/postcss/blob/master/docs/source-maps.md
 316 [Midas]:              https://github.com/ben-eb/midas
 317 [SCSS]:               https://github.com/postcss/postcss-scss
 318
 319 ### Node.js 0.10 and the Promise API
 320
 321 If you want to run PostCSS in Node.js 0.10, add the [Promise polyfill]:
 322
 323 ```js
 324 require('es6-promise').polyfill();
 325 var postcss = require('postcss');
 326 ```
 327
 328 [Promise polyfill]: https://github.com/jakearchibald/es6-promise
 329
 330 ## IDE Integration
 331
 332 ### Atom
 333
 334 * [`language-postcss`] adds PostCSS and [SugarSS] highlight.
 335 * [`source-preview-postcss`] previews your output CSS in a separate, live pane.
 336
 337 [SugarSS]: https://github.com/postcss/sugarss
 338
 339 ### Sublime Text
 340
 341 * [`Syntax-highlighting-for-PostCSS`] adds PostCSS highlight.
 342
 343 [`Syntax-highlighting-for-PostCSS`]: https://github.com/hudochenkov/Syntax-highlighting-for-PostCSS
 344 [`source-preview-postcss`]:          https://atom.io/packages/source-preview-postcss
 345 [`language-postcss`]:                https://atom.io/packages/language-postcss
 346
 347 ### Vim
 348
 349 * [`postcss.vim`] adds PostCSS highlight.
 350
 351 [`postcss.vim`]: https://github.com/stephenway/postcss.vim
 352
 353 ### WebStorm
 354
 355 WebStorm 2016.3 [has] built-in PostCSS support.
 356
 357 [has]: https://blog.jetbrains.com/webstorm/2016/08/webstorm-2016-3-early-access-preview/