1 # PostCSS [![Travis Build Status][travis-img]][travis] [![AppVeyor Build Status][appveyor-img]][appveyor] [![Gitter][chat-img]][chat]
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">
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
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.
18 PostCSS is used by industry leaders including Wikipedia, Twitter, Alibaba,
19 and JetBrains. The [Autoprefixer] PostCSS plugin is one of the most popular
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).
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>.
30 [Autoprefixer]: https://github.com/postcss/autoprefixer
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">
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
44 If you have any new ideas, [PostCSS plugin development] is really easy.
46 [searchable catalog]: http://postcss.parts
47 [plugins list]: https://github.com/postcss/postcss/blob/master/docs/plugins.md
49 ### Solve Global CSS Problem
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
59 * [`cq-prolyfill`] adds container query support, allowing styles that respond
60 to the width of the parent.
62 ### Use Future CSS, Today
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
69 ### Better CSS Readability
71 * [`precss`] contains plugins for Sass-like features, like variables, nesting,
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.
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.
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.
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.
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
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.
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.
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
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)
163 More articles and videos you can find on [awesome-postcss](https://github.com/jjaderg/awesome-postcss) list.
167 You can start using PostCSS in just two steps:
169 1. Find and add PostCSS extensions for your build tool.
170 2. [Select plugins] and add them to your PostCSS process.
172 [Select plugins]: http://postcss.parts
176 Use [`postcss-loader`] in `webpack.config.js`:
186 'css-loader?importLoaders=1',
195 Then create `postcss.config.js`:
201 require('autoprefixer')
206 [`postcss-loader`]: https://github.com/postcss/postcss-loader
210 Use [`gulp-postcss`] and [`gulp-sourcemaps`].
213 gulp.task('css', function () {
214 var postcss = require('gulp-postcss');
215 var sourcemaps = require('gulp-sourcemaps');
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/') );
225 [`gulp-sourcemaps`]: https://github.com/floridoo/gulp-sourcemaps
226 [`gulp-postcss`]: https://github.com/postcss/gulp-postcss
230 To use PostCSS from your command-line interface or with npm scripts
231 there is [`postcss-cli`].
234 postcss --use autoprefixer -c options.json -o main.css css/*.css
237 [`postcss-cli`]: https://github.com/postcss/postcss-cli
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.
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.
249 var postcss = require('postcss-js');
250 var prefixer = postcss.sync([ require('autoprefixer') ]);
252 prefixer({ display: 'flex' }); //=> { display: ['-webkit-box', '-webkit-flex', '-ms-flexbox', 'flex'] }
255 [`postcss-js`]: https://github.com/postcss/postcss-js
256 [Browserify]: http://browserify.org/
257 [webpack]: https://webpack.github.io/
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)
275 For other environments, you can use the JS API:
278 const postcss = require('postcss');
279 const precss = require('precss');
280 const autoprefixer = require('autoprefixer');
282 fs.readFile('src/app.css', (err, css) => {
283 postcss([precss, autoprefixer])
284 .process(css, { from: 'src/app.css', to: 'dest/app.css' })
286 fs.writeFile('dest/app.css', result.css);
287 if ( result.map ) fs.writeFile('dest/app.css.map', result.map);
292 Read the [PostCSS API documentation] for more details about the JS API.
294 All PostCSS runners should pass [PostCSS Runner Guidelines].
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
301 Most PostCSS runners accept two parameters:
303 * An array of plugins.
304 * An object of options.
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).
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
319 ### Node.js 0.10 and the Promise API
321 If you want to run PostCSS in Node.js 0.10, add the [Promise polyfill]:
324 require('es6-promise').polyfill();
325 var postcss = require('postcss');
328 [Promise polyfill]: https://github.com/jakearchibald/es6-promise
334 * [`language-postcss`] adds PostCSS and [SugarSS] highlight.
335 * [`source-preview-postcss`] previews your output CSS in a separate, live pane.
337 [SugarSS]: https://github.com/postcss/sugarss
341 * [`Syntax-highlighting-for-PostCSS`] adds PostCSS highlight.
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
349 * [`postcss.vim`] adds PostCSS highlight.
351 [`postcss.vim`]: https://github.com/stephenway/postcss.vim
355 WebStorm 2016.3 [has] built-in PostCSS support.
357 [has]: https://blog.jetbrains.com/webstorm/2016/08/webstorm-2016-3-early-access-preview/