diff options
Diffstat (limited to 'node_modules/browserslist/README.md')
| -rw-r--r-- | node_modules/browserslist/README.md | 589 |
1 files changed, 589 insertions, 0 deletions
diff --git a/node_modules/browserslist/README.md b/node_modules/browserslist/README.md new file mode 100644 index 0000000..fc5d213 --- /dev/null +++ b/node_modules/browserslist/README.md @@ -0,0 +1,589 @@ +# Browserslist [![Cult Of Martians][cult-img]][cult] + +<img width="120" height="120" alt="Browserslist logo by Anton Lovchikov" + src="https://browserslist.github.io/browserslist/logo.svg" align="right"> + +The config to share target browsers and Node.js versions between different +front-end tools. It is used in: + +* [Autoprefixer] +* [Babel] +* [postcss-preset-env] +* [eslint-plugin-compat] +* [stylelint-no-unsupported-browser-features] +* [postcss-normalize] +* [obsolete-webpack-plugin] + +All tools will find target browsers automatically, +when you add the following to `package.json`: + +```js + "browserslist": [ + "last 1 version", + "> 1%", + "maintained node versions", + "not dead" + ] +``` + +Or in `.browserslistrc` config: + +```yaml +# Browsers that we support + +last 1 version +> 1% +maintained node versions +not dead +``` + +Developers set versions list in queries like `last 2 version` +to be free from updating versions manually. +Browserslist will use [Can I Use] data for this queries. + +Browserslist will take queries from tool option, +`browserslist` config, `.browserslistrc` config, +`browserslist` section in `package.json` or environment variables. + +[Browserslist Example] shows how every tool uses Browserslist. + +[cult-img]: https://cultofmartians.com/assets/badges/badge.svg +[cult]: https://cultofmartians.com/done.html + +<a href="https://evilmartians.com/?utm_source=browserslist"> + <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" + alt="Sponsored by Evil Martians" width="236" height="54"> +</a> + +[stylelint-no-unsupported-browser-features]: https://github.com/ismay/stylelint-no-unsupported-browser-features +[eslint-plugin-compat]: https://github.com/amilajack/eslint-plugin-compat +[Browserslist Example]: https://github.com/browserslist/browserslist-example +[postcss-preset-env]: https://github.com/jonathantneal/postcss-preset-env +[postcss-normalize]: https://github.com/jonathantneal/postcss-normalize +[Autoprefixer]: https://github.com/postcss/autoprefixer +[Can I Use]: https://caniuse.com/ +[Babel]: https://github.com/babel/babel/tree/master/packages/babel-preset-env +[obsolete-webpack-plugin]: https://github.com/ElemeFE/obsolete-webpack-plugin + +## Table of Contents + +1. [Tools](#tools) +2. [Best Practices](#best-practices) +3. [Queries](#queries) +4. [Config File](#config-file) +5. [Shareable Configs](#shareable-configs) +6. [Configuring for Different Environments](#configuring-for-different-environments) +7. [Custom Usage Data](#custom-usage-data) +8. [JS API](#js-api) +9. [Environment Variables](#environment-variables) +10. [Cache](#cache) + +## Tools + +* [`browserslist-ga`] and [`browserslist-ga-export`] download your website + browsers statistics to use it in `> 0.5% in my stats` query. +* [`browserslist-useragent-regexp`] compiles Browserslist query to a RegExp + to test browser useragent. +* [`browserslist-useragent-ruby`] is a Ruby library to checks browser + by user agent string to match Browserslist. +* [`browserslist-browserstack`] runs BrowserStack tests for all browsers + in Browserslist config. +* [`caniuse-api`] returns browsers which support some specific feature. +* Run `npx browserslist` in your project directory to see project’s + target browsers. This CLI tool is built-in and available in any project + with Autoprefixer. + +[`browserslist-useragent-regexp`]: https://github.com/browserslist/browserslist-useragent-regexp +[`browserslist-useragent-ruby`]: https://github.com/browserslist/browserslist-useragent-ruby +[`browserslist-browserstack`]: https://github.com/xeroxinteractive/browserslist-browserstack +[`browserslist-ga-export`]: https://github.com/browserslist/browserslist-ga-export +[`browserslist-useragent`]: https://github.com/pastelsky/browserslist-useragent +[`browserslist-ga`]: https://github.com/browserslist/browserslist-ga +[`caniuse-api`]: https://github.com/Nyalab/caniuse-api + + +## Best Practices + +* Select browsers directly (`last 2 Chrome versions`) only if you are making + a web app for a kiosk with one browser. There are a lot of browsers + on the market. If you are making general web app you should respect + browsers diversity. +* There is a `defaults` query, which gives a reasonable configuration + for most users: + + ```json + "browserslist": [ + "defaults" + ] + ``` + +* If you want to change the default set of browsers we recommend to combine + `last 1 version`, `not dead` with `> 0.2%` (or `> 1% in US`, + `> 1% in my stats`). `last n versions` adds too many dead browsers + and does not add popular old versions. Choosing a percentage above `0.2%` + will in the long run make popular browsers even more popular. We might run + into a monopoly and stagnation situation, as we had with Internet Explorer 6. + Please use this setting with caution. +* Don’t remove browsers just because you don’t know them. Opera Mini has + 100 million users in Africa and it is more popular in the global market + than Microsoft Edge. Chinese QQ Browsers has more market share than Firefox + and desktop Safari combined. + + +## Queries + +Browserslist will use browsers and Node.js versions query +from one of these sources: + +1. `browserslist` key in `package.json` file in current or parent directories. + **We recommend this way.** +2. `.browserslistrc` config file in current or parent directories. +3. `browserslist` config file in current or parent directories. +4. `BROWSERSLIST` environment variable. +5. If the above methods did not produce a valid result + Browserslist will use defaults: + `> 0.5%, last 2 versions, Firefox ESR, not dead`. + + +### Query Composition + +An `or` combiner can use the keyword `or` as well as `,`. +`last 1 version or > 1%` is equal to `last 1 version, > 1%`. + +`and` query combinations are also supported to perform an +intersection of the previous query: `last 1 version and > 1%`. + +There is 3 different ways to combine queries as depicted below. First you start +with a single query and then we combine the queries to get our final list. + +Obviously you can *not* start with a `not` combiner, since there is no left-hand +side query to combine it with. + +| Query combiner type | Illustration | Example | +| ------------------- | :----------: | ------- | +|`or`/`,` combiner <br> (union) |  | `> .5% or last 2 versions` <br> `> .5%, last 2 versions` | +| `and` combiner <br> (intersection) |  | `> .5% and last 2 versions` | +| `not` combiner <br> (relative complement) |  | `> .5% and not last 2 versions` <br> `> .5% or not last 2 versions` <br> `> .5%, not last 2 versions` | + +_A quick way to test your query is to do `npx browserslist '> 0.5%, not IE 11'` +in your terminal._ + + +### Full List + +You can specify the browser and Node.js versions by queries (case insensitive): + +* `> 5%`: browsers versions selected by global usage statistics. + `>=`, `<` and `<=` work too. +* `> 5% in US`: uses USA usage statistics. It accepts [two-letter country code]. +* `> 5% in alt-AS`: uses Asia region usage statistics. List of all region codes + can be found at [`caniuse-lite/data/regions`]. +* `> 5% in my stats`: uses [custom usage data]. +* `cover 99.5%`: most popular browsers that provide coverage. +* `cover 99.5% in US`: same as above, with [two-letter country code]. +* `cover 99.5% in my stats`: uses [custom usage data]. +* `maintained node versions`: all Node.js versions, which are [still maintained] + by Node.js Foundation. +* `node 10` and `node 10.4`: selects latest Node.js `10.x.x` + or `10.4.x` release. +* `current node`: Node.js version used by Browserslist right now. +* `extends browserslist-config-mycompany`: take queries from + `browserslist-config-mycompany` npm package. +* `ie 6-8`: selects an inclusive range of versions. +* `Firefox > 20`: versions of Firefox newer than 20. + `>=`, `<` and `<=` work too. It also works with Node.js. +* `iOS 7`: the iOS browser version 7 directly. +* `Firefox ESR`: the latest [Firefox ESR] version. +* `PhantomJS 2.1` and `PhantomJS 1.9`: selects Safari versions similar + to PhantomJS runtime. +* `unreleased versions` or `unreleased Chrome versions`: + alpha and beta versions. +* `last 2 major versions` or `last 2 iOS major versions`: + all minor/patch releases of last 2 major versions. +* `since 2015` or `last 2 years`: all versions released since year 2015 + (also `since 2015-03` and `since 2015-03-10`). +* `dead`: browsers without official support or updates for 24 months. + Right now it is `IE 10`, `IE_Mob 10`, `BlackBerry 10`, `BlackBerry 7`, + `Samsung 4` and `OperaMobile 12.1`. +* `last 2 versions`: the last 2 versions for *each* browser. +* `last 2 Chrome versions`: the last 2 versions of Chrome browser. +* `defaults`: Browserslist’s default browsers + (`> 0.5%, last 2 versions, Firefox ESR, not dead`). +* `not ie <= 8`: exclude browsers selected by previous queries. + +You can add `not ` to any query. + +[`caniuse-lite/data/regions`]: https://github.com/ben-eb/caniuse-lite/tree/master/data/regions +[two-letter country code]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements +[custom usage data]: #custom-usage-data +[still maintained]: https://github.com/nodejs/Release +[Can I Use]: https://caniuse.com/ + + +### Debug + +Run `npx browserslist` in project directory to see what browsers was selected +by your queries. + +```sh +$ npx browserslist +and_chr 61 +and_ff 56 +and_qq 1.2 +and_uc 11.4 +android 56 +baidu 7.12 +bb 10 +chrome 62 +edge 16 +firefox 56 +ios_saf 11 +opera 48 +safari 11 +samsung 5 +``` + + +### Browsers + +Names are case insensitive: + +* `Android` for Android WebView. +* `Baidu` for Baidu Browser. +* `BlackBerry` or `bb` for Blackberry browser. +* `Chrome` for Google Chrome. +* `ChromeAndroid` or `and_chr` for Chrome for Android +* `Edge` for Microsoft Edge. +* `Electron` for Electron framework. It will be converted to Chrome version. +* `Explorer` or `ie` for Internet Explorer. +* `ExplorerMobile` or `ie_mob` for Internet Explorer Mobile. +* `Firefox` or `ff` for Mozilla Firefox. +* `FirefoxAndroid` or `and_ff` for Firefox for Android. +* `iOS` or `ios_saf` for iOS Safari. +* `Node` for Node.js. +* `Opera` for Opera. +* `OperaMini` or `op_mini` for Opera Mini. +* `OperaMobile` or `op_mob` for Opera Mobile. +* `QQAndroid` or `and_qq` for QQ Browser for Android. +* `Safari` for desktop Safari. +* `Samsung` for Samsung Internet. +* `UCAndroid` or `and_uc` for UC Browser for Android. +* `kaios` for KaiOS Browser. + + +## Config File + +### `package.json` + +If you want to reduce config files in project root, you can specify +browsers in `package.json` with `browserslist` key: + +```json +{ + "private": true, + "dependencies": { + "autoprefixer": "^6.5.4" + }, + "browserslist": [ + "last 1 version", + "> 1%", + "IE 10" + ] +} +``` + + +### `.browserslistrc` + +Separated Browserslist config should be named `.browserslistrc` +and have browsers queries split by a new line. Comments starts with `#` symbol: + +```yaml +# Browsers that we support + +last 1 version +> 1% +IE 10 # sorry +``` + +Browserslist will check config in every directory in `path`. +So, if tool process `app/styles/main.css`, you can put config to root, +`app/` or `app/styles`. + +You can specify direct path in `BROWSERSLIST_CONFIG` environment variables. + + +## Shareable Configs + +You can use the following query to reference an exported Browserslist config +from another package: + +```json + "browserslist": [ + "extends browserslist-config-mycompany" + ] +``` + +For security reasons, external configuration only supports packages that have +the `browserslist-config-` prefix. npm scoped packages are also supported, by +naming or prefixing the module with `@scope/browserslist-config`, such as +`@scope/browserslist-config` or `@scope/browserslist-config-mycompany`. + +If you don’t accept Browserslist queries from users, you can disable the +validation by using the `dangerousExtend` option: + +```js +browserslist(queries, { path, dangerousExtend: true }) +``` + +Because this uses `npm`'s resolution, you can also reference specific files +in a package: + +```json + "browserslist": [ + "extends browserslist-config-mycompany/desktop", + "extends browserslist-config-mycompany/mobile" + ] +``` + +When writing a shared Browserslist package, just export an array. +`browserslist-config-mycompany/index.js`: + +```js +module.exports = [ + 'last 1 version', + '> 1%', + 'ie 10' +] +``` + + +## Configuring for Different Environments + +You can also specify different browser queries for various environments. +Browserslist will choose query according to `BROWSERSLIST_ENV` or `NODE_ENV` +variables. If none of them is declared, Browserslist will firstly look +for `production` queries and then use defaults. + +In `package.json`: + +```js + "browserslist": { + "production": [ + "> 1%", + "ie 10" + ], + "modern": [ + "last 1 chrome version", + "last 1 firefox version" + ], + "ssr": [ + "node 12" + ] + } +``` + +In `.browserslistrc` config: + +```ini +[production] +> 1% +ie 10 + +[modern] +last 1 chrome version +last 1 firefox version + +[ssr] +node 12 +``` + + +## Custom Usage Data + +If you have a website, you can query against the usage statistics of your site. +[`browserslist-ga`] will ask access to Google Analytics and then generate +`browserslist-stats.json`: + +``` +npx browserslist-ga +``` + +Or you can use [`browserslist-ga-export`] to convert Google Analytics data without giving a password for Google account. + +You can generate usage statistics file by any other method. File format should +be like: + +```js +{ + "ie": { + "6": 0.01, + "7": 0.4, + "8": 1.5 + }, + "chrome": { + … + }, + … +} +``` + +Note that you can query against your custom usage data while also querying +against global or regional data. For example, the query +`> 1% in my stats, > 5% in US, 10%` is permitted. + +[`browserslist-ga-export`]: https://github.com/browserslist/browserslist-ga-export +[`browserslist-ga`]: https://github.com/browserslist/browserslist-ga +[Can I Use]: https://caniuse.com/ + + +## JS API + +```js +const browserslist = require('browserslist') + +// Your CSS/JS build tool code +function process (source, opts) { + const browsers = browserslist(opts.overrideBrowserslist, { + stats: opts.stats, + path: opts.file, + env: opts.env + }) + // Your code to add features for selected browsers +} +``` + +Queries can be a string `"> 1%, IE 10"` +or an array `['> 1%', 'IE 10']`. + +If a query is missing, Browserslist will look for a config file. +You can provide a `path` option (that can be a file) to find the config file +relatively to it. + +Options: + +* `path`: file or a directory path to look for config file. Default is `.`. +* `env`: what environment section use from config. Default is `production`. +* `stats`: custom usage statistics data. +* `config`: path to config if you want to set it manually. +* `ignoreUnknownVersions`: do not throw on direct query (like `ie 12`). + Default is `false.` +* `dangerousExtend`: Disable security checks for `extend` query. + Default is `false.` +* `mobileToDesktop`: Use desktop browsers if Can I Use doesn’t have data + about this mobile version. For instance, Browserslist will return + `chrome 20` on `and_chr 20` query (Can I Use has only data only about + latest versions of mobile browsers). Default is `false`. + +For non-JS environment and debug purpose you can use CLI tool: + +```sh +browserslist "> 1%, IE 10" +``` + +You can get total users coverage for selected browsers by JS API: + +```js +browserslist.coverage(browserslist('> 1%')) +//=> 81.4 +``` + +```js +browserslist.coverage(browserslist('> 1% in US'), 'US') +//=> 83.1 +``` + +```js +browserslist.coverage(browserslist('> 1% in my stats'), 'my stats') +//=> 83.1 +``` + +```js +browserslist.coverage(browserslist('> 1% in my stats', { stats }), stats) +//=> 82.2 +``` + +Or by CLI: + +```sh +$ browserslist --coverage "> 1%" +These browsers account for 81.4% of all users globally +``` + +```sh +$ browserslist --coverage=US "> 1% in US" +These browsers account for 83.1% of all users in the US +``` + +```sh +$ browserslist --coverage "> 1% in my stats" +These browsers account for 83.1% of all users in custom statistics +``` + +```sh +$ browserslist --coverage "> 1% in my stats" --stats=./stats.json +These browsers account for 83.1% of all users in custom statistics +``` + + +## Environment Variables + +If some tool use Browserslist inside, you can change browsers settings +by [environment variables]: + +* `BROWSERSLIST` with browsers queries. + + ```sh + BROWSERSLIST="> 5%" gulp css + ``` + +* `BROWSERSLIST_CONFIG` with path to config file. + + ```sh + BROWSERSLIST_CONFIG=./config/browserslist gulp css + ``` + +* `BROWSERSLIST_ENV` with environments string. + + ```sh + BROWSERSLIST_ENV="development" gulp css + ``` + +* `BROWSERSLIST_STATS` with path to the custom usage data + for `> 1% in my stats` query. + + ```sh + BROWSERSLIST_STATS=./config/usage_data.json gulp css + ``` + +* `BROWSERSLIST_DISABLE_CACHE` if you want to disable config reading cache. + + ```sh + BROWSERSLIST_DISABLE_CACHE=1 gulp css + ``` + +[environment variables]: https://en.wikipedia.org/wiki/Environment_variable + + +## Cache + +Browserslist caches the configuration it reads from `package.json` and +`browserslist` files, as well as knowledge about the existence of files, +for the duration of the hosting process. + +To clear these caches, use: + +```js +browserslist.clearCaches() +``` + +To disable the caching altogether, set the `BROWSERSLIST_DISABLE_CACHE` +environment variable. + + +## Security Contact + +To report a security vulnerability, please use the [Tidelift security contact]. +Tidelift will coordinate the fix and disclosure. + +[Tidelift security contact]: https://tidelift.com/security |