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 Google, Twitter, Alibaba,
19 and Shopify. 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 [Autoprefixer]: https://github.com/postcss/autoprefixer
28 <a href="https://evilmartians.com/?utm_source=postcss">
29 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
30 alt="Sponsored by Evil Martians" width="236" height="54">
35 Currently, PostCSS has more than 200 plugins. You can find all of the plugins
36 in the [plugins list] or in the [searchable catalog]. Below is a list
37 of our favorite plugins — the best demonstrations of what can be built
40 If you have any new ideas, [PostCSS plugin development] is really easy.
42 [searchable catalog]: http://postcss.parts
43 [plugins list]: https://github.com/postcss/postcss/blob/master/docs/plugins.md
45 ### Solve Global CSS Problem
47 * [`postcss-use`] allows you to explicitly set PostCSS plugins within CSS
48 and execute them only for the current file.
49 * [`postcss-modules`] and [`react-css-modules`] automatically isolate
50 selectors within components.
51 * [`postcss-autoreset`] is an alternative to using a global reset
52 that is better for isolatable components.
53 * [`postcss-initial`] adds `all: initial` support, which resets
55 * [`cq-prolyfill`] adds container query support, allowing styles that respond
56 to the width of the parent.
58 ### Use Future CSS, Today
60 * [`autoprefixer`] adds vendor prefixes, using data from Can I Use.
61 * [`postcss-cssnext`] allows you to use future CSS features today
62 (includes `autoprefixer`).
64 ### Better CSS Readability
66 * [`precss`] contains plugins for Sass-like features, like variables, nesting,
68 * [`postcss-sorting`] sorts the content of rules and at-rules.
69 * [`short`] adds and extends numerous shorthand properties.
73 * [`postcss-assets`] inserts image dimensions and inlines files.
74 * [`postcss-sprites`] generates image sprites.
75 * [`font-magician`] generates all the `@font-face` rules needed in CSS.
76 * [`postcss-inline-svg`] allows you to inline SVG and customize its styles.
77 * [`postcss-write-svg`] allows you to write simple SVG directly in your CSS.
81 * [`stylelint`] is a modular stylesheet linter.
82 * [`stylefmt`] is a tool that automatically formats CSS
83 according `stylelint` rules.
84 * [`doiuse`] lints CSS for browser support, using data from Can I Use.
85 * [`colorguard`] helps you maintain a consistent color palette.
89 * [`lost`] is a feature-rich `calc()` grid system.
90 * [`cssnano`] is a modular CSS minifier.
91 * [`rtlcss`] mirrors styles for right-to-left locales.
93 [PostCSS plugin development]: https://github.com/postcss/postcss/blob/master/docs/writing-a-plugin.md
94 [`postcss-inline-svg`]: https://github.com/TrySound/postcss-inline-svg
95 [`react-css-modules`]: https://github.com/gajus/react-css-modules
96 [`postcss-autoreset`]: https://github.com/maximkoretskiy/postcss-autoreset
97 [`postcss-write-svg`]: https://github.com/jonathantneal/postcss-write-svg
98 [`postcss-initial`]: https://github.com/maximkoretskiy/postcss-initial
99 [`postcss-sprites`]: https://github.com/2createStudio/postcss-sprites
100 [`postcss-modules`]: https://github.com/outpunk/postcss-modules
101 [`postcss-sorting`]: https://github.com/hudochenkov/postcss-sorting
102 [`postcss-cssnext`]: http://cssnext.io/
103 [`postcss-assets`]: https://github.com/assetsjs/postcss-assets
104 [`font-magician`]: https://github.com/jonathantneal/postcss-font-magician
105 [`autoprefixer`]: https://github.com/postcss/autoprefixer
106 [`cq-prolyfill`]: https://github.com/ausi/cq-prolyfill
107 [`postcss-use`]: https://github.com/postcss/postcss-use
108 [`css-modules`]: https://github.com/css-modules/css-modules
109 [`colorguard`]: https://github.com/SlexAxton/css-colorguard
110 [`stylelint`]: https://github.com/stylelint/stylelint
111 [`stylefmt`]: https://github.com/morishitter/stylefmt
112 [`cssnano`]: http://cssnano.co/
113 [`precss`]: https://github.com/jonathantneal/precss
114 [`doiuse`]: https://github.com/anandthakker/doiuse
115 [`rtlcss`]: https://github.com/MohammadYounes/rtlcss
116 [`short`]: https://github.com/jonathantneal/postcss-short
117 [`lost`]: https://github.com/peterramsing/lost
121 PostCSS can transform styles in any syntax, not just CSS.
122 If there is not yet support for your favorite syntax,
123 you can write a parser and/or stringifier to extend PostCSS.
125 * [`sugarss`] is a indent-based syntax like Sass or Stylus.
126 * [`postcss-scss`] allows you to work with SCSS
127 *(but does not compile SCSS to CSS)*.
128 * [`postcss-less`] allows you to work with Less
129 *(but does not compile LESS to CSS)*.
130 * [`postcss-js`] allows you to write styles in JS or transform
131 React Inline Styles, Radium or JSS.
132 * [`postcss-safe-parser`] finds and fixes CSS syntax errors.
133 * [`midas`] converts a CSS string to highlighted HTML.
135 [`postcss-safe-parser`]: https://github.com/postcss/postcss-safe-parser
136 [`postcss-less`]: https://github.com/webschik/postcss-less
137 [`postcss-scss`]: https://github.com/postcss/postcss-scss
138 [`postcss-js`]: https://github.com/postcss/postcss-js
139 [`sugarss`]: https://github.com/postcss/sugarss
140 [`midas`]: https://github.com/ben-eb/midas
144 * [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/)
145 * [What PostCSS Really Is; What It Really Does](http://davidtheclark.com/its-time-for-everyone-to-learn-about-postcss/)
146 * [PostCSS Guides](http://webdesign.tutsplus.com/series/postcss-deep-dive--cms-889)
150 You can start using PostCSS in just two steps:
152 1. Find and add PostCSS extensions for your build tool.
153 2. [Select plugins] and add them to your PostCSS process.
155 [Select plugins]: http://postcss.parts
159 Use [`gulp-postcss`] and [`gulp-sourcemaps`].
162 gulp.task('css', function () {
163 var postcss = require('gulp-postcss');
164 var sourcemaps = require('gulp-sourcemaps');
166 return gulp.src('src/**/*.css')
167 .pipe( sourcemaps.init() )
168 .pipe( postcss([ require('autoprefixer'), require('precss') ]) )
169 .pipe( sourcemaps.write('.') )
170 .pipe( gulp.dest('build/') );
174 [`gulp-sourcemaps`]: https://github.com/floridoo/gulp-sourcemaps
175 [`gulp-postcss`]: https://github.com/postcss/gulp-postcss
179 Use [`postcss-loader`]:
187 loader: "style-loader!css-loader!postcss-loader"
191 postcss: function () {
192 return [require('autoprefixer'), require('precss')];
197 [`postcss-loader`]: https://github.com/postcss/postcss-loader
201 To use PostCSS from your command-line interface or with npm scripts
202 there is [`postcss-cli`].
205 postcss --use autoprefixer -c options.json -o main.css css/*.css
208 [`postcss-cli`]: https://github.com/postcss/postcss-cli
212 To apply PostCSS plugins to React Inline Styles, JSS, Radium
213 and other CSS-in-JS, you can use [`postcss-js`] and transforms style objects.
216 var postcss = require('postcss-js');
217 var prefixer = postcss.sync([ require('autoprefixer') ]);
219 prefixer({ display: 'flex' }); //=> { display: ['-webkit-box', '-webkit-flex', '-ms-flexbox', 'flex'] }
222 [`postcss-js`]: https://github.com/postcss/postcss-js
226 * **Grunt**: [`grunt-postcss`](https://github.com/nDmitry/grunt-postcss)
227 * **HTML**: [`posthtml-postcss`](https://github.com/posthtml/posthtml-postcss)
228 * **Stylus**: [`poststylus`](https://github.com/seaneking/poststylus)
229 * **Rollup**: [`rollup-plugin-postcss`](https://github.com/egoist/rollup-plugin-postcss)
230 * **Brunch**: [`postcss-brunch`](https://github.com/iamvdo/postcss-brunch)
231 * **Broccoli**: [`broccoli-postcss`](https://github.com/jeffjewiss/broccoli-postcss)
232 * **Meteor**: [`postcss`](https://atmospherejs.com/juliancwirko/postcss)
233 * **ENB**: [`enb-postcss`](https://github.com/awinogradov/enb-postcss)
234 * **Fly**: [`fly-postcss`](https://github.com/postcss/fly-postcss)
235 * **Start**: [`start-postcss`](https://github.com/start-runner/postcss)
236 * **Connect/Express**: [`postcss-middleware`](https://github.com/jedmao/postcss-middleware)
240 For other environments, you can use the JS API:
243 var postcss = require('postcss');
244 postcss([ require('autoprefixer'), require('cssnano') ])
245 .process(css, { from: 'src/app.css', to: 'app.css' })
246 .then(function (result) {
247 fs.writeFileSync('app.css', result.css);
248 if ( result.map ) fs.writeFileSync('app.css.map', result.map);
252 Read the [PostCSS API documentation] for more details about the JS API.
254 All PostCSS runners should pass [PostCSS Runner Guidelines].
256 [PostCSS Runner Guidelines]: https://github.com/postcss/postcss/blob/master/docs/guidelines/runner.md
257 [PostCSS API documentation]: https://github.com/postcss/postcss/blob/master/docs/api.md
261 Most PostCSS runners accept two parameters:
263 * An array of plugins.
264 * An object of options.
268 * `syntax`: an object providing a syntax parser and a stringifier.
269 * `parser`: a special syntax parser (for example, [SCSS]).
270 * `stringifier`: a special syntax output generator (for example, [Midas]).
271 * `map`: [source map options].
272 * `from`: the input file name (most runners set it automatically).
273 * `to`: the output file name (most runners set it automatically).
275 [source map options]: https://github.com/postcss/postcss/blob/master/docs/source-maps.md
276 [Midas]: https://github.com/ben-eb/midas
277 [SCSS]: https://github.com/postcss/postcss-scss
279 ### Node.js 0.10 and the Promise API
281 If you want to run PostCSS in Node.js 0.10, add the [Promise polyfill]:
284 require('es6-promise').polyfill();
285 var postcss = require('postcss');
288 [Promise polyfill]: https://github.com/jakearchibald/es6-promise