diff options
Diffstat (limited to 'node_modules/cssnano/node_modules/autoprefixer/README.md')
| -rw-r--r-- | node_modules/cssnano/node_modules/autoprefixer/README.md | 568 |
1 files changed, 568 insertions, 0 deletions
diff --git a/node_modules/cssnano/node_modules/autoprefixer/README.md b/node_modules/cssnano/node_modules/autoprefixer/README.md new file mode 100644 index 00000000..d57fc1c7 --- /dev/null +++ b/node_modules/cssnano/node_modules/autoprefixer/README.md @@ -0,0 +1,568 @@ +# Autoprefixer [![Build Status][ci-img]][ci] + +<img align="right" width="94" height="71" + src="http://postcss.github.io/autoprefixer/logo.svg" + title="Autoprefixer logo by Anton Lovchikov"> + +[PostCSS] plugin to parse CSS and add vendor prefixes to CSS rules using values +from [Can I Use]. It is [recommended] by Google and used in Twitter and Taobao. + +Write your CSS rules without vendor prefixes (in fact, forget about them +entirely): + +```css +:fullscreen a { + display: flex +} +``` + +Autoprefixer will use the data based on current browser popularity and property +support to apply prefixes for you. You can try the [interactive demo] +of Autoprefixer. + +```css +:-webkit-full-screen a { + display: -webkit-box; + display: flex +} +:-moz-full-screen a { + display: flex +} +:-ms-fullscreen a { + display: -ms-flexbox; + display: flex +} +:fullscreen a { + display: -webkit-box; + display: -ms-flexbox; + display: flex +} +``` + +Twitter account for news and releases: [@autoprefixer]. + +<a href="https://evilmartians.com/?utm_source=autoprefixer"> +<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"> +</a> + +[interactive demo]: http://autoprefixer.github.io/ +[@autoprefixer]: https://twitter.com/autoprefixer +[recommended]: https://developers.google.com/web/tools/setup/setup-buildtools#dont-trip-up-with-vendor-prefixes +[Can I Use]: http://caniuse.com/ +[PostCSS]: https://github.com/postcss/postcss +[ci-img]: https://travis-ci.org/postcss/autoprefixer.svg +[ci]: https://travis-ci.org/postcss/autoprefixer + +## Features + +### Write Pure CSS + +Working with Autoprefixer is simple: just forget about vendor prefixes +and write normal CSS according to the latest W3C specs. You don’t need +a special language (like Sass) or remember where you must use mixins. + +Autoprefixer supports selectors (like `:fullscreen` and `::selection`), +unit function (`calc()`), at‑rules (`@supports` and `@keyframes`) +and properties. + +Because Autoprefixer is a postprocessor for CSS, +you can also use it with preprocessors such as Sass, Stylus or LESS. + +### Flexbox, Filters, etc. + +Just write normal CSS according to the latest W3C specs and Autoprefixer +will produce the code for old browsers. + +```css +a { + display: flex; +} +``` + +compiles to: + +```css +a { + display: -webkit-box; + display: -webkit-flex; + display: -ms-flexbox; + display: flex +} +``` + +Autoprefixer has [27 special hacks] to fix web browser differences. + +[27 special hacks]: https://github.com/postcss/autoprefixer/tree/master/lib/hacks + +### Only Actual Prefixes + +Autoprefixer utilizes the most recent data from [Can I Use] +to add only necessary vendor prefixes. + +It also removes old, unnecessary prefixes from your CSS +(like `border-radius` prefixes, produced by many CSS libraries). + +```css +a { + -webkit-border-radius: 5px; + border-radius: 5px; +} +``` + +compiles to: + +```css +a { + border-radius: 5px; +} +``` + +[Can I Use]: http://caniuse.com/ + +## Browsers + +Autoprefixer uses [Browserslist], so you can specify the browsers +you want to target in your project by queries like `last 2 versions` +or `> 5%`. + +The best way to provide browsers is `browserslist` config +or `package.json` with `browserslist` key. Put it in your project root. + +We recommend to avoid Autoprefixer option and use `browserslist` config +or `package.json`. In this case browsers will be shared with other tools +like [babel-preset-env] or [Stylelint]. + +See [Browserslist docs] for queries, browser names, config format, +and default value. + +[Browserslist docs]: https://github.com/ai/browserslist#queries +[babel-preset-env]: https://github.com/babel/babel-preset-env +[Browserslist]: https://github.com/ai/browserslist +[Stylelint]: http://stylelint.io/ + +## Outdated Prefixes + +By default, Autoprefixer also removes outdated prefixes. + +You can disable this behavior with the `remove: false` option. If you have +no legacy code, this option will make Autoprefixer about 10% faster. + +Also, you can set the `add: false` option. Autoprefixer will only clean outdated +prefixes, but will not add any new prefixes. + +Autoprefixer adds new prefixes between any unprefixed properties and already +written prefixes in your CSS. If it will break the expected prefixes order, +you can clean all prefixes from your CSS and then +add the necessary prefixes again: + +```js +var cleaner = postcss([ autoprefixer({ add: false, browsers: [] }) ]); +var prefixer = postcss([ autoprefixer ]); + +cleaner.process(css).then(function (cleaned) { + return prefixer.process(cleaned.css) +}).then(function (result) { + console.log(result.css); +}); +``` + +## FAQ + +#### No prefixes in production + +Many other tools contain Autoprefixer. For example, webpack uses Autoprefixer +to minify CSS by cleaning unnecessary prefixes. + +If you set browsers list to Autoprefixer by `browsers` option, only first +Autoprefixer will know your browsers. Autoprefixer inside webpack will use +default browsers list. As result, webpack will remove prefixes, that first +Autoprefixer added. + +You need to put your browsers to [`browserslist` config] in project root — +as result all tools (Autoprefixer, cssnano, doiuse, cssnext) will use same +browsers list. + +[`browserslist` config]: https://github.com/ai/browserslist#config-file + +#### Does it add polyfills? + +No. Autoprefixer only adds prefixes. + +Most new CSS features will require client side JavaScript to handle a new +behavior correctly. + +Depending on what you consider to be a “polyfill”, you can take a look at some +other tools and libraries. If you are just looking for syntax sugar, +you might take a look at: + +- [Oldie], a PostCSS plugin that handles some IE hacks (opacity, rgba, etc). +- [postcss-flexbugs-fixes], a PostCSS plugin to fix flexbox issues. +- [cssnext], a tool that allows you to write standard CSS syntax non-implemented + yet in browsers (custom properties, custom media, color functions, etc). + +[postcss-flexbugs-fixes]: https://github.com/luisrudge/postcss-flexbugs-fixes +[cssnext]: https://github.com/MoOx/postcss-cssnext +[Oldie]: https://github.com/jonathantneal/oldie + +#### Why doesn’t Autoprefixer add prefixes to `border-radius`? + +Developers are often surprised by how few prefixes are required today. +If Autoprefixer doesn’t add prefixes to your CSS, check if they’re still +required on [Can I Use]. + +There is a [list with all supported] properties, values, and selectors. + +[list with all supported]: https://github.com/postcss/autoprefixer/wiki/support-list +[Can I Use]: http://caniuse.com/ + +#### Why Autoprefixer uses unprefixed properties in `@-webkit-keyframes`? + +Browser teams can remove some prefixes before others. So we try to use +all combinations of prefixed/unprefixed values. + +#### How to work with legacy `-webkit-` only code? + +Autoprefixer needs unprefixed property to add prefixes. So if you only +wrote `-webkit-gradient` without W3C’s `gradient`, +Autoprefixer will not add other prefixes. + +But [PostCSS] has a plugins to convert CSS to unprefixed state. +Use them before Autoprefixer: + +* [postcss-unprefix] +* [postcss-flexboxfixer] +* [postcss-gradientfixer] + +[postcss-gradientfixer]: https://github.com/hallvors/postcss-gradientfixer +[postcss-flexboxfixer]: https://github.com/hallvors/postcss-flexboxfixer +[postcss-unprefix]: https://github.com/yisibl/postcss-unprefix + +#### Does Autoprefixer add `-epub-` prefix? + +No, Autoprefixer works only with browsers prefixes from Can I Use. +But you can use [postcss-epub](https://github.com/Rycochet/postcss-epub) +for prefixing ePub3 properties. + +#### Why doesn’t Autoprefixer transform generic font-family `system-ui`? + +`system-ui` is technically not a prefix and the transformation is not future-proof. But you can use [postcss-font-family-system-ui](https://github.com/JLHwung/postcss-font-family-system-ui) to transform `system-ui` to a practical font-family list. + +## Usage + +### Gulp + +In Gulp you can use [gulp-postcss] with `autoprefixer` npm package. + +```js +gulp.task('autoprefixer', function () { + var postcss = require('gulp-postcss'); + var sourcemaps = require('gulp-sourcemaps'); + var autoprefixer = require('autoprefixer'); + + return gulp.src('./src/*.css') + .pipe(sourcemaps.init()) + .pipe(postcss([ autoprefixer() ])) + .pipe(sourcemaps.write('.')) + .pipe(gulp.dest('./dest')); +}); +``` + +With `gulp-postcss` you also can combine Autoprefixer +with [other PostCSS plugins]. + +[other PostCSS plugins]: https://github.com/postcss/postcss#plugins +[gulp-postcss]: https://github.com/postcss/gulp-postcss + +### Webpack + +In [webpack] you can use [postcss-loader] with `autoprefixer` +and [other PostCSS plugins]. + +```js +module.exports = { + module: { + loaders: [ + { + test: /\.css$/, + loader: "style-loader!css-loader!postcss-loader" + } + ] + } +} +``` + +And create a `postcss.config.js` with: + +```js +module.exports = { + plugins: [ + require('autoprefixer') + ] +} +``` + +[other PostCSS plugins]: https://github.com/postcss/postcss#plugins +[postcss-loader]: https://github.com/postcss/postcss-loader +[webpack]: http://webpack.github.io/ + +### Grunt + +In Grunt you can use [grunt-postcss] with `autoprefixer` npm package. + +```js +module.exports = function(grunt) { + grunt.loadNpmTasks('grunt-postcss'); + + grunt.initConfig({ + postcss: { + options: { + map: true, + processors: [ + require('autoprefixer') + ] + }, + dist: { + src: 'css/*.css' + } + } + }); + + grunt.registerTask('default', ['postcss:dist']); +}; +``` + +With `grunt-postcss` you also can combine Autoprefixer +with [other PostCSS plugins]. + +[other PostCSS plugins]: https://github.com/postcss/postcss#plugins +[grunt-postcss]: https://github.com/nDmitry/grunt-postcss + +### Other Build Tools: + +* **Ruby on Rails**: [autoprefixer-rails] +* **Brunch**: [postcss-brunch] +* **Broccoli**: [broccoli-postcss] +* **Middleman**: [middleman-autoprefixer] +* **Mincer**: add `autoprefixer` npm package and enable it: + `environment.enable('autoprefixer')` +* **Jekyll**: add `autoprefixer-rails` and `jekyll-assets` to `Gemfile` + +[middleman-autoprefixer]: https://github.com/middleman/middleman-autoprefixer +[autoprefixer-rails]: https://github.com/ai/autoprefixer-rails +[broccoli-postcss]: https://github.com/jeffjewiss/broccoli-postcss +[postcss-brunch]: https://github.com/iamvdo/postcss-brunch + +### Preprocessors + +* **Less**: [less-plugin-autoprefix] +* **Stylus**: [autoprefixer-stylus] +* **Compass**: [autoprefixer-rails#compass] + +[less-plugin-autoprefix]: https://github.com/less/less-plugin-autoprefix +[autoprefixer-stylus]: https://github.com/jenius/autoprefixer-stylus +[autoprefixer-rails#compass]: https://github.com/ai/autoprefixer-rails#compass + +### CSS-in-JS + +There is [postcss-js] to use Autoprefixer in React Inline Styles, [Free Style], +Radium and other CSS-in-JS solutions. + +```js +let prefixer = postcssJs.sync([ autoprefixer ]); +let style = prefixer({ + display: 'flex' +}); +``` + +[postcss-js]: https://github.com/postcss/postcss-js +[Free Style]: https://github.com/blakeembrey/free-style + +### GUI Tools + +* [CodeKit](https://incident57.com/codekit/help.html#autoprefixer) +* [Prepros](https://prepros.io) + +### CLI + +You can use the [postcss-cli] to run Autoprefixer from CLI: + +```sh +npm install --global postcss-cli autoprefixer +postcss --use autoprefixer *.css -d build/ +``` + +See `postcss -h` for help. + +[postcss-cli]: https://github.com/postcss/postcss-cli + +### JavaScript + +You can use Autoprefixer with [PostCSS] in your Node.js application +or if you want to develop an Autoprefixer plugin for new environment. + +```js +var autoprefixer = require('autoprefixer'); +var postcss = require('postcss'); + +postcss([ autoprefixer ]).process(css).then(function (result) { + result.warnings().forEach(function (warn) { + console.warn(warn.toString()); + }); + console.log(result.css); +}); +``` + +There is also [standalone build] for the browser or as a non-Node.js runtime. + +You can use [html-autoprefixer] to process HTML with inlined CSS. + +[html-autoprefixer]: https://github.com/RebelMail/html-autoprefixer +[standalone build]: https://raw.github.com/ai/autoprefixer-rails/master/vendor/autoprefixer.js +[PostCSS]: https://github.com/postcss/postcss + +### Text Editors and IDE + +Autoprefixer should be used in assets build tools. Text editor plugins are not +a good solution, because prefixes decrease code readability and you will need +to change value in all prefixed properties. + +I recommend you to learn how to use build tools like [Gulp]. +They work much better and will open you a whole new world of useful plugins +and automatization. + +But, if you can’t move to a build tool, you can use text editor plugins: + +* [Sublime Text](https://github.com/sindresorhus/sublime-autoprefixer) +* [Brackets](https://github.com/mikaeljorhult/brackets-autoprefixer) +* [Atom Editor](https://github.com/sindresorhus/atom-autoprefixer) +* [Visual Studio](http://vswebessentials.com/) + +[Gulp]: http://gulpjs.com/ + +## Warnings + +Autoprefixer uses the [PostCSS warning API] to warn about really important problems +in your CSS: + +* Old direction syntax in gradients. +* Old unprefixed `display: box` instead of `display: flex` + by latest specification version. + +You can get warnings from `result.warnings()`: + +```js +result.warnings().forEach(function (warn) { + console.warn(warn.toString()); +}); +``` + +Every Autoprefixer runner should display this warnings. + +[PostCSS warning API]: https://github.com/postcss/postcss/blob/master/docs/api.md#warning-class + +## Disabling + +Autoprefixer was designed to have no interface – it just works. +If you need some browser specific hack just write a prefixed property +after the unprefixed one. + +```css +a { + transform: scale(0.5); + -moz-transform: scale(0.6); +} +``` + +If some prefixes were generated in a wrong way, +please create an issue on GitHub. + +Autoprefixer has 4 features, which can be disabled by options: + +* `supports: false` will disable `@supports` parameters prefixing. +* `flexbox: false` will disable flexbox properties prefixing. + Or `flexbox: "no-2009"` will add prefixes only for final and IE + versions of specification. +* `grid: false` will disable Grid Layout prefixes for IE. +* `remove: false` will disable cleaning outdated prefixes. + +If you do not need Autoprefixer in some part of your CSS, +you can use control comments to disable Autoprefixer. + +```css +a { + transition: 1s; /* it will be prefixed */ +} + +b { + /* autoprefixer: off */ + transition: 1s; /* it will not be prefixed */ +} +``` + +Control comments disable Autoprefixer within the whole rule in which +you place it. In the above example, Autoprefixer will be disabled +in the entire `b` rule scope, not only after the comment. + +You can also use comments recursively: + +```css +/* autoprefixer: off */ +@supports (transition: all) { + /* autoprefixer: on */ + a { + /* autoprefixer: off */ + } +} +``` + +In Sass/SCSS you can use all the disable options above, add an exclamation mark +in the start of comment: `/*! autoprefixer: off */`. + +## Options + +Function `autoprefixer(options)` returns new PostCSS plugin. +See [PostCSS API] for plugin usage documentation. + +```js +var plugin = autoprefixer({ cascade: false }); +``` + +There are 8 options: + +* `browsers` (array): list of browsers query (like `last 2 versions`), + which are supported in your project. We recommend to use `browserslist` + config or `browserslist` key in `package.json`, rather than this option + to share browsers with other tools. See [Browserslist docs] for available + queries and default value. +* `env` (string): environment for Browserslist. +* `cascade` (boolean): should Autoprefixer use Visual Cascade, + if CSS is uncompressed. Default: `true` +* `add` (boolean): should Autoprefixer add prefixes. Default is `true`. +* `remove` (boolean): should Autoprefixer [remove outdated] prefixes. + Default is `true`. +* `supports` (boolean): should Autoprefixer add prefixes for `@supports` + parameters. Default is `true`. +* `flexbox` (boolean|string): should Autoprefixer add prefixes for flexbox + properties. With `"no-2009"` value Autoprefixer will add prefixes only + for final and IE versions of specification. Default is `true`. +* `grid` (boolean): should Autoprefixer add IE prefixes for Grid Layout + properties. Default is `true`. +* `stats` (object): custom [usage statistics] for `> 10% in my stats` + browsers query. + +Plugin object has `info()` method for debugging purpose. + +You can use PostCSS processor to process several CSS files +to increase performance. + +[usage statistics]: https://github.com/ai/browserslist#custom-usage-data +[PostCSS API]: https://github.com/postcss/postcss/blob/master/docs/api.md + +## Debug + +You can check which browsers are selected and which properties will be prefixed: + +```js +var info = autoprefixer().info(); +console.log(info); +``` |