1 | # PostCSS [![Gitter][chat-img]][chat]
|
2 |
|
3 | <img align="right" width="95" height="95"
|
4 | alt="Philosopher’s stone, logo of PostCSS"
|
5 | src="http://postcss.github.io/postcss/logo.svg">
|
6 |
|
7 | [chat-img]: https://img.shields.io/badge/Gitter-Join_the_PostCSS_chat-brightgreen.svg
|
8 | [chat]: https://gitter.im/postcss/postcss
|
9 |
|
10 | PostCSS is a tool for transforming styles with JS plugins.
|
11 | These plugins can lint your CSS, support variables and mixins,
|
12 | transpile future CSS syntax, inline images, and more.
|
13 |
|
14 | PostCSS is used by industry leaders including Wikipedia, Twitter, Alibaba,
|
15 | and JetBrains. The [Autoprefixer] PostCSS plugin is one of the most popular
|
16 | CSS processors.
|
17 |
|
18 | PostCSS takes a CSS file and provides an API to analyze and modify its rules
|
19 | (by transforming them into an [Abstract Syntax Tree]).
|
20 | This API can then be used by [plugins] to do a lot of useful things,
|
21 | e.g. to find errors automatically insert vendor prefixes.
|
22 |
|
23 | **Support / Discussion:** [Gitter](https://gitter.im/postcss/postcss)<br>
|
24 | **Twitter account:** [@postcss](https://twitter.com/postcss)<br>
|
25 | **VK.com page:** [postcss](https://vk.com/postcss)<br>
|
26 | **中文翻译**: [`README-cn.md`](./README-cn.md)
|
27 |
|
28 | For PostCSS commercial support (consulting, improving the front-end culture
|
29 | of your company, PostCSS plugins), contact [Evil Martians]
|
30 | at <surrender@evilmartians.com>.
|
31 |
|
32 | [Abstract Syntax Tree]: https://en.wikipedia.org/wiki/Abstract_syntax_tree
|
33 | [Evil Martians]: https://evilmartians.com/?utm_source=postcss
|
34 | [Autoprefixer]: https://github.com/postcss/autoprefixer
|
35 | [plugins]: https://github.com/postcss/postcss#plugins
|
36 |
|
37 | <a href="https://evilmartians.com/?utm_source=postcss">
|
38 | <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
|
39 | alt="Sponsored by Evil Martians" width="236" height="54">
|
40 | </a>
|
41 |
|
42 | ## Plugins
|
43 |
|
44 | Currently, PostCSS has more than 200 plugins. You can find all of the plugins
|
45 | in the [plugins list] or in the [searchable catalog]. Below is a list
|
46 | of our favorite plugins — the best demonstrations of what can be built
|
47 | on top of PostCSS.
|
48 |
|
49 | If you have any new ideas, [PostCSS plugin development] is really easy.
|
50 |
|
51 | [searchable catalog]: http://postcss.parts
|
52 | [plugins list]: https://github.com/postcss/postcss/blob/master/docs/plugins.md
|
53 |
|
54 | ### Solve Global CSS Problem
|
55 |
|
56 | * [`postcss-use`] allows you to explicitly set PostCSS plugins within CSS
|
57 | and execute them only for the current file.
|
58 | * [`postcss-modules`] and [`react-css-modules`] automatically isolate
|
59 | selectors within components.
|
60 | * [`postcss-autoreset`] is an alternative to using a global reset
|
61 | that is better for isolatable components.
|
62 | * [`postcss-initial`] adds `all: initial` support, which resets
|
63 | all inherited styles.
|
64 | * [`cq-prolyfill`] adds container query support, allowing styles that respond
|
65 | to the width of the parent.
|
66 |
|
67 | ### Use Future CSS, Today
|
68 |
|
69 | * [`autoprefixer`] adds vendor prefixes, using data from Can I Use.
|
70 | * [`postcss-preset-env`] allows you to use future CSS features today.
|
71 |
|
72 | ### Better CSS Readability
|
73 |
|
74 | * [`precss`] contains plugins for Sass-like features, like variables, nesting,
|
75 | and mixins.
|
76 | * [`postcss-sorting`] sorts the content of rules and at-rules.
|
77 | * [`postcss-utilities`] includes the most commonly used shortcuts and helpers.
|
78 | * [`short`] adds and extends numerous shorthand properties.
|
79 |
|
80 | ### Images and Fonts
|
81 |
|
82 | * [`postcss-assets`] inserts image dimensions and inlines files.
|
83 | * [`postcss-sprites`] generates image sprites.
|
84 | * [`font-magician`] generates all the `@font-face` rules needed in CSS.
|
85 | * [`postcss-inline-svg`] allows you to inline SVG and customize its styles.
|
86 | * [`postcss-write-svg`] allows you to write simple SVG directly in your CSS.
|
87 |
|
88 | ### Linters
|
89 |
|
90 | * [`stylelint`] is a modular stylesheet linter.
|
91 | * [`stylefmt`] is a tool that automatically formats CSS
|
92 | according `stylelint` rules.
|
93 | * [`doiuse`] lints CSS for browser support, using data from Can I Use.
|
94 | * [`colorguard`] helps you maintain a consistent color palette.
|
95 |
|
96 | ### Other
|
97 |
|
98 | * [`postcss-rtl`] combines both-directional (left-to-right and right-to-left) styles in one CSS file.
|
99 | * [`cssnano`] is a modular CSS minifier.
|
100 | * [`lost`] is a feature-rich `calc()` grid system.
|
101 | * [`rtlcss`] mirrors styles for right-to-left locales.
|
102 |
|
103 | [PostCSS plugin development]: https://github.com/postcss/postcss/blob/master/docs/writing-a-plugin.md
|
104 | [`postcss-inline-svg`]: https://github.com/TrySound/postcss-inline-svg
|
105 | [`postcss-preset-env`]: https://github.com/jonathantneal/postcss-preset-env
|
106 | [`react-css-modules`]: https://github.com/gajus/react-css-modules
|
107 | [`postcss-autoreset`]: https://github.com/maximkoretskiy/postcss-autoreset
|
108 | [`postcss-write-svg`]: https://github.com/jonathantneal/postcss-write-svg
|
109 | [`postcss-utilities`]: https://github.com/ismamz/postcss-utilities
|
110 | [`postcss-initial`]: https://github.com/maximkoretskiy/postcss-initial
|
111 | [`postcss-sprites`]: https://github.com/2createStudio/postcss-sprites
|
112 | [`postcss-modules`]: https://github.com/outpunk/postcss-modules
|
113 | [`postcss-sorting`]: https://github.com/hudochenkov/postcss-sorting
|
114 | [`postcss-assets`]: https://github.com/assetsjs/postcss-assets
|
115 | [`font-magician`]: https://github.com/jonathantneal/postcss-font-magician
|
116 | [`autoprefixer`]: https://github.com/postcss/autoprefixer
|
117 | [`cq-prolyfill`]: https://github.com/ausi/cq-prolyfill
|
118 | [`postcss-rtl`]: https://github.com/vkalinichev/postcss-rtl
|
119 | [`postcss-use`]: https://github.com/postcss/postcss-use
|
120 | [`css-modules`]: https://github.com/css-modules/css-modules
|
121 | [`colorguard`]: https://github.com/SlexAxton/css-colorguard
|
122 | [`stylelint`]: https://github.com/stylelint/stylelint
|
123 | [`stylefmt`]: https://github.com/morishitter/stylefmt
|
124 | [`cssnano`]: http://cssnano.co
|
125 | [`precss`]: https://github.com/jonathantneal/precss
|
126 | [`doiuse`]: https://github.com/anandthakker/doiuse
|
127 | [`rtlcss`]: https://github.com/MohammadYounes/rtlcss
|
128 | [`short`]: https://github.com/jonathantneal/postcss-short
|
129 | [`lost`]: https://github.com/peterramsing/lost
|
130 |
|
131 | ## Syntaxes
|
132 |
|
133 | PostCSS can transform styles in any syntax, not just CSS.
|
134 | If there is not yet support for your favorite syntax,
|
135 | you can write a parser and/or stringifier to extend PostCSS.
|
136 |
|
137 | * [`sugarss`] is a indent-based syntax like Sass or Stylus.
|
138 | * [`postcss-syntax`] switch syntax automatically by file extensions.
|
139 | * [`postcss-html`] parsing styles in `<style>` tags of HTML-like files.
|
140 | * [`postcss-markdown`] parsing styles in code blocks of Markdown files.
|
141 | * [`postcss-jsx`] parsing CSS in template / object literals of source files.
|
142 | * [`postcss-styled`] parsing CSS in template literals of source files.
|
143 | * [`postcss-scss`] allows you to work with SCSS
|
144 | *(but does not compile SCSS to CSS)*.
|
145 | * [`postcss-sass`] allows you to work with Sass
|
146 | *(but does not compile Sass to CSS)*.
|
147 | * [`postcss-less`] allows you to work with Less
|
148 | *(but does not compile LESS to CSS)*.
|
149 | * [`postcss-less-engine`] allows you to work with Less
|
150 | *(and DOES compile LESS to CSS using true Less.js evaluation)*.
|
151 | * [`postcss-js`] allows you to write styles in JS or transform
|
152 | React Inline Styles, Radium or JSS.
|
153 | * [`postcss-safe-parser`] finds and fixes CSS syntax errors.
|
154 | * [`midas`] converts a CSS string to highlighted HTML.
|
155 |
|
156 | [`postcss-less-engine`]: https://github.com/Crunch/postcss-less
|
157 | [`postcss-safe-parser`]: https://github.com/postcss/postcss-safe-parser
|
158 | [`postcss-syntax`]: https://github.com/gucong3000/postcss-syntax
|
159 | [`postcss-html`]: https://github.com/gucong3000/postcss-html
|
160 | [`postcss-markdown`]: https://github.com/gucong3000/postcss-markdown
|
161 | [`postcss-jsx`]: https://github.com/gucong3000/postcss-jsx
|
162 | [`postcss-styled`]: https://github.com/gucong3000/postcss-styled
|
163 | [`postcss-scss`]: https://github.com/postcss/postcss-scss
|
164 | [`postcss-sass`]: https://github.com/AleshaOleg/postcss-sass
|
165 | [`postcss-less`]: https://github.com/webschik/postcss-less
|
166 | [`postcss-js`]: https://github.com/postcss/postcss-js
|
167 | [`sugarss`]: https://github.com/postcss/sugarss
|
168 | [`midas`]: https://github.com/ben-eb/midas
|
169 |
|
170 | ## Articles
|
171 |
|
172 | * [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)
|
173 | * [What PostCSS Really Is; What It Really Does](http://davidtheclark.com/its-time-for-everyone-to-learn-about-postcss)
|
174 | * [PostCSS Guides](http://webdesign.tutsplus.com/series/postcss-deep-dive--cms-889)
|
175 |
|
176 | More articles and videos you can find on [awesome-postcss](https://github.com/jjaderg/awesome-postcss) list.
|
177 |
|
178 | ## Books
|
179 |
|
180 | * [Mastering PostCSS for Web Design](https://www.packtpub.com/web-development/mastering-postcss-web-design) by Alex Libby, Packt. (June 2016)
|
181 |
|
182 | ## Usage
|
183 |
|
184 | You can start using PostCSS in just two steps:
|
185 |
|
186 | 1. Find and add PostCSS extensions for your build tool.
|
187 | 2. [Select plugins] and add them to your PostCSS process.
|
188 |
|
189 | [Select plugins]: http://postcss.parts
|
190 |
|
191 | ### CSS-in-JS
|
192 |
|
193 | The best way to use PostCSS with CSS-in-JS is [`astroturf`].
|
194 | Add its loader to your `webpack.config.js`:
|
195 |
|
196 | ```js
|
197 | module.exports = {
|
198 | module: {
|
199 | rules: [
|
200 | {
|
201 | test: /\.css$/,
|
202 | use: ['style-loader', 'postcss-loader'],
|
203 | },
|
204 | {
|
205 | test: /\.jsx?$/,
|
206 | use: ['babel-loader', 'astroturf/loader'],
|
207 | }
|
208 | ]
|
209 | }
|
210 | }
|
211 | ```
|
212 |
|
213 | Then create `postcss.config.js`:
|
214 |
|
215 | ```js
|
216 | module.exports = {
|
217 | plugins: [
|
218 | require('autoprefixer'),
|
219 | require('postcss-nested')
|
220 | ]
|
221 | }
|
222 | ```
|
223 |
|
224 | [`astroturf`]: https://github.com/4Catalyzer/astroturf
|
225 |
|
226 | ### Parcel
|
227 |
|
228 | [Parcel] has built-in PostCSS support. It already uses Autoprefixer
|
229 | and cssnano. If you want to change plugins, create `postcss.config.js`
|
230 | in project’s root:
|
231 |
|
232 | ```js
|
233 | module.exports = {
|
234 | plugins: [
|
235 | require('autoprefixer'),
|
236 | require('postcss-nested')
|
237 | ]
|
238 | }
|
239 | ```
|
240 |
|
241 | Parcel will even automatically install these plugins for you.
|
242 |
|
243 | > Please, be aware of [the several issues in Version 1](https://github.com/parcel-bundler/parcel/labels/CSS%20Preprocessing). Notice, [Version 2](https://github.com/parcel-bundler/parcel/projects/5) may resolve the issues via [issue #2157](https://github.com/parcel-bundler/parcel/issues/2157).
|
244 |
|
245 | [Parcel]: https://parceljs.org
|
246 |
|
247 | ### Webpack
|
248 |
|
249 | Use [`postcss-loader`] in `webpack.config.js`:
|
250 |
|
251 | ```js
|
252 | module.exports = {
|
253 | module: {
|
254 | rules: [
|
255 | {
|
256 | test: /\.css$/,
|
257 | exclude: /node_modules/,
|
258 | use: [
|
259 | {
|
260 | loader: 'style-loader',
|
261 | },
|
262 | {
|
263 | loader: 'css-loader',
|
264 | options: {
|
265 | importLoaders: 1,
|
266 | }
|
267 | },
|
268 | {
|
269 | loader: 'postcss-loader'
|
270 | }
|
271 | ]
|
272 | }
|
273 | ]
|
274 | }
|
275 | }
|
276 | ```
|
277 |
|
278 | Then create `postcss.config.js`:
|
279 |
|
280 | ```js
|
281 | module.exports = {
|
282 | plugins: [
|
283 | require('precss'),
|
284 | require('autoprefixer')
|
285 | ]
|
286 | }
|
287 | ```
|
288 |
|
289 | [`postcss-loader`]: https://github.com/postcss/postcss-loader
|
290 |
|
291 | ### Gulp
|
292 |
|
293 | Use [`gulp-postcss`] and [`gulp-sourcemaps`].
|
294 |
|
295 | ```js
|
296 | gulp.task('css', () => {
|
297 | const postcss = require('gulp-postcss')
|
298 | const sourcemaps = require('gulp-sourcemaps')
|
299 |
|
300 | return gulp.src('src/**/*.css')
|
301 | .pipe( sourcemaps.init() )
|
302 | .pipe( postcss([ require('precss'), require('autoprefixer') ]) )
|
303 | .pipe( sourcemaps.write('.') )
|
304 | .pipe( gulp.dest('build/') )
|
305 | })
|
306 | ```
|
307 |
|
308 | [`gulp-sourcemaps`]: https://github.com/floridoo/gulp-sourcemaps
|
309 | [`gulp-postcss`]: https://github.com/postcss/gulp-postcss
|
310 |
|
311 | ### npm run / CLI
|
312 |
|
313 | To use PostCSS from your command-line interface or with npm scripts
|
314 | there is [`postcss-cli`].
|
315 |
|
316 | ```sh
|
317 | postcss --use autoprefixer -c options.json -o main.css css/*.css
|
318 | ```
|
319 |
|
320 | [`postcss-cli`]: https://github.com/postcss/postcss-cli
|
321 |
|
322 | ### Browser
|
323 |
|
324 | If you want to compile CSS string in browser (for instance, in live edit
|
325 | tools like CodePen), just use [Browserify] or [webpack]. They will pack
|
326 | PostCSS and plugins files into a single file.
|
327 |
|
328 | To apply PostCSS plugins to React Inline Styles, JSS, Radium
|
329 | and other [CSS-in-JS], you can use [`postcss-js`] and transforms style objects.
|
330 |
|
331 | ```js
|
332 | var postcss = require('postcss-js')
|
333 | var prefixer = postcss.sync([ require('autoprefixer') ])
|
334 |
|
335 | prefixer({ display: 'flex' }) //=> { display: ['-webkit-box', '-webkit-flex', '-ms-flexbox', 'flex'] }
|
336 | ```
|
337 |
|
338 | [`postcss-js`]: https://github.com/postcss/postcss-js
|
339 | [Browserify]: http://browserify.org/
|
340 | [CSS-in-JS]: https://github.com/MicheleBertoli/css-in-js
|
341 | [webpack]: https://webpack.github.io/
|
342 |
|
343 | ### Runners
|
344 |
|
345 | * **Grunt**: [`grunt-postcss`](https://github.com/nDmitry/grunt-postcss)
|
346 | * **HTML**: [`posthtml-postcss`](https://github.com/posthtml/posthtml-postcss)
|
347 | * **Stylus**: [`poststylus`](https://github.com/seaneking/poststylus)
|
348 | * **Rollup**: [`rollup-plugin-postcss`](https://github.com/egoist/rollup-plugin-postcss)
|
349 | * **Brunch**: [`postcss-brunch`](https://github.com/brunch/postcss-brunch)
|
350 | * **Broccoli**: [`broccoli-postcss`](https://github.com/jeffjewiss/broccoli-postcss)
|
351 | * **Meteor**: [`postcss`](https://atmospherejs.com/juliancwirko/postcss)
|
352 | * **ENB**: [`enb-postcss`](https://github.com/awinogradov/enb-postcss)
|
353 | * **Taskr**: [`taskr-postcss`](https://github.com/lukeed/taskr/tree/master/packages/postcss)
|
354 | * **Start**: [`start-postcss`](https://github.com/start-runner/postcss)
|
355 | * **Connect/Express**: [`postcss-middleware`](https://github.com/jedmao/postcss-middleware)
|
356 |
|
357 | ### JS API
|
358 |
|
359 | For other environments, you can use the JS API:
|
360 |
|
361 | ```js
|
362 | const autoprefixer = require('autoprefixer')
|
363 | const postcss = require('postcss')
|
364 | const precss = require('precss')
|
365 | const fs = require('fs')
|
366 |
|
367 | fs.readFile('src/app.css', (err, css) => {
|
368 | postcss([precss, autoprefixer])
|
369 | .process(css, { from: 'src/app.css', to: 'dest/app.css' })
|
370 | .then(result => {
|
371 | fs.writeFile('dest/app.css', result.css, () => true)
|
372 | if ( result.map ) {
|
373 | fs.writeFile('dest/app.css.map', result.map, () => true)
|
374 | }
|
375 | })
|
376 | })
|
377 | ```
|
378 |
|
379 | Read the [PostCSS API documentation] for more details about the JS API.
|
380 |
|
381 | All PostCSS runners should pass [PostCSS Runner Guidelines].
|
382 |
|
383 | [PostCSS Runner Guidelines]: https://github.com/postcss/postcss/blob/master/docs/guidelines/runner.md
|
384 | [PostCSS API documentation]: http://api.postcss.org/postcss.html
|
385 |
|
386 | ### Options
|
387 |
|
388 | Most PostCSS runners accept two parameters:
|
389 |
|
390 | * An array of plugins.
|
391 | * An object of options.
|
392 |
|
393 | Common options:
|
394 |
|
395 | * `syntax`: an object providing a syntax parser and a stringifier.
|
396 | * `parser`: a special syntax parser (for example, [SCSS]).
|
397 | * `stringifier`: a special syntax output generator (for example, [Midas]).
|
398 | * `map`: [source map options].
|
399 | * `from`: the input file name (most runners set it automatically).
|
400 | * `to`: the output file name (most runners set it automatically).
|
401 |
|
402 | [source map options]: https://github.com/postcss/postcss/blob/master/docs/source-maps.md
|
403 | [Midas]: https://github.com/ben-eb/midas
|
404 | [SCSS]: https://github.com/postcss/postcss-scss
|
405 |
|
406 | ### Treat Warnings as Errors
|
407 |
|
408 | In some situations it might be helpful to fail the build on any warning
|
409 | from PostCSS or one of its plugins. This guarantees that no warnings
|
410 | go unnoticed, and helps to avoid bugs. While there is no option to enable
|
411 | treating warnings as errors, it can easily be done
|
412 | by adding `postcss-fail-on-warn` plugin in the end of PostCSS plugins:
|
413 |
|
414 | ```js
|
415 | module.exports = {
|
416 | plugins: [
|
417 | require('autoprefixer'),
|
418 | require('postcss-fail-on-warn')
|
419 | ]
|
420 | }
|
421 | ```
|
422 |
|
423 |
|
424 | ## Editors & IDE Integration
|
425 |
|
426 | ### VS Code
|
427 |
|
428 | * [`csstools.postcss`] adds support for PostCSS, `postcss-preset-env`
|
429 | and CSS Modules.
|
430 |
|
431 | [`csstools.postcss`]: https://marketplace.visualstudio.com/items?itemName=csstools.postcss
|
432 |
|
433 | ### Atom
|
434 |
|
435 | * [`language-postcss`] adds PostCSS and [SugarSS] highlight.
|
436 | * [`source-preview-postcss`] previews your output CSS in a separate, live pane.
|
437 |
|
438 | [SugarSS]: https://github.com/postcss/sugarss
|
439 |
|
440 | ### Sublime Text
|
441 |
|
442 | * [`Syntax-highlighting-for-PostCSS`] adds PostCSS highlight.
|
443 |
|
444 | [`Syntax-highlighting-for-PostCSS`]: https://github.com/hudochenkov/Syntax-highlighting-for-PostCSS
|
445 | [`source-preview-postcss`]: https://atom.io/packages/source-preview-postcss
|
446 | [`language-postcss`]: https://atom.io/packages/language-postcss
|
447 |
|
448 | ### Vim
|
449 |
|
450 | * [`postcss.vim`] adds PostCSS highlight.
|
451 |
|
452 | [`postcss.vim`]: https://github.com/stephenway/postcss.vim
|
453 |
|
454 | ### WebStorm
|
455 |
|
456 | WebStorm 2016.3 [has] built-in PostCSS support.
|
457 |
|
458 | [has]: https://blog.jetbrains.com/webstorm/2016/08/webstorm-2016-3-early-access-preview/
|
459 |
|
460 |
|
461 | ## Security Contact
|
462 |
|
463 | To report a security vulnerability, please use the [Tidelift security contact].
|
464 | Tidelift will coordinate the fix and disclosure.
|
465 |
|
466 | [Tidelift security contact]: https://tidelift.com/security
|