Opal-Estate-Pro/node_modules/autoprefixer/README.md

569 lines
17 KiB
Markdown
Raw Normal View History

2019-09-13 06:27:52 +02:00
# 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 dont need
a special language (like Sass) or remember where you must use mixins.
Autoprefixer supports selectors (like `:fullscreen` and `::selection`),
unit function (`calc()`), atrules (`@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 doesnt Autoprefixer add prefixes to `border-radius`?
Developers are often surprised by how few prefixes are required today.
If Autoprefixer doesnt add prefixes to your CSS, check if theyre 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 W3Cs `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 doesnt 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 cant 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);
```