.config/coc/extensions/node_modules/coc-prettier/node_modules/browserslist/README.md

   1 # Browserslist
   2
   3 <img align="right" width="120" height="120"
   4      src="./logo.svg" alt="Browserslist logo by Anton Lovchikov">
   5
   6 Library to share target browsers between different front-end tools.
   7 It is used in:
   8
   9 * [Autoprefixer]
  10 * [babel-preset-env]
  11   (external config in `package.json` or `browserslist` will be supported in 7.0)
  12 * [postcss-preset-env]
  13 * [eslint-plugin-compat]
  14 * [stylelint-no-unsupported-browser-features]
  15 * [postcss-normalize]
  16
  17 All tools that rely on Browserslist will find its config automatically,
  18 when you add the following to `package.json`:
  19
  20 ```json
  21 {
  22   "browserslist": [
  23     "> 1%",
  24     "last 2 versions"
  25   ]
  26 }
  27 ```
  28
  29 Or in `.browserslistrc` config:
  30
  31 ```yaml
  32 # Browsers that we support
  33
  34 > 1%
  35 Last 2 versions
  36 IE 10 # sorry
  37 ```
  38
  39 Developers set browsers list in queries like `last 2 version`
  40 to be free from updating browser versions manually.
  41 Browserslist will use [Can I Use] data for this queries.
  42
  43 Browserslist will take browsers queries from tool option,
  44 `browserslist` config, `.browserslistrc` config,
  45 `browserslist` section in `package.json` or environment variables.
  46
  47 You can test Browserslist queries in [online demo].
  48
  49 <a href="https://evilmartians.com/?utm_source=browserslist">
  50   <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
  51     alt="Sponsored by Evil Martians"
  52     width="236"
  53     height="54"
  54   \>
  55 </a>
  56
  57 [stylelint-no-unsupported-browser-features]: https://github.com/ismay/stylelint-no-unsupported-browser-features
  58 [eslint-plugin-compat]:                      https://github.com/amilajack/eslint-plugin-compat
  59 [postcss-preset-env]: https://github.com/jonathantneal/postcss-preset-env
  60 [babel-preset-env]:                          https://github.com/babel/babel/tree/master/packages/babel-preset-env
  61 [postcss-normalize]:                         https://github.com/jonathantneal/postcss-normalize
  62 [Autoprefixer]:                              https://github.com/postcss/autoprefixer
  63 [online demo]:                               http://browserl.ist/
  64 [Can I Use]:                                 http://caniuse.com/
  65
  66 ## Tools
  67
  68 * [`browserslist-useragent`] checks browser by user agent string
  69   to match Browserslist target browsers query.
  70 * [`caniuse-api`] returns browsers which support some specific feature.
  71 * Run `npx browserslist` in your project directory to see project’s
  72   target browsers. This CLI tool is built-in and available in any project
  73   with Autoprefixer.
  74
  75 [`browserslist-useragent`]: https://github.com/pastelsky/browserslist-useragent
  76 [`caniuse-api`]:            https://github.com/Nyalab/caniuse-api
  77
  78 ## Queries
  79
  80 Browserslist will use browsers query from one of this sources:
  81
  82 1. Tool options. For example `browsers` option in Autoprefixer.
  83 2. `BROWSERSLIST` environment variable.
  84 3. `browserslist` config file in current or parent directories.
  85 3. `.browserslistrc` config file in current or parent directories.
  86 4. `browserslist` key in `package.json` file in current or parent directories.
  87    **We recommend this way.**
  88 5. If the above methods did not produce a valid result
  89    Browserslist will use defaults: `> 1%, last 2 versions, Firefox ESR`.
  90
  91 You can specify the versions by queries (case insensitive):
  92
  93 * `last 2 versions`: the last 2 versions for each browser.
  94 * `last 2 Chrome versions`: the last 2 versions of Chrome browser.
  95 * `> 5%`: versions selected by global usage statistics.
  96   `>=`, `<` and `<=` work too.
  97 * `> 5% in US`: uses USA usage statistics. It accepts [two-letter country code].
  98 * `> 5% in alt-AS`: uses Asia region usage statistics. List of all region codes
  99   can be found at [`caniuse-lite/data/regions`].
 100 * `> 5% in my stats`: uses [custom usage data].
 101 * `extends browserslist-config-mycompany`: take queries from
 102   `browserslist-config-mycompany` npm package.
 103 * `ie 6-8`: selects an inclusive range of versions.
 104 * `Firefox > 20`: versions of Firefox newer than 20.
 105   `>=`, `<` and `<=` work too.
 106 * `iOS 7`: the iOS browser version 7 directly.
 107 * `Firefox ESR`: the latest [Firefox ESR] version.
 108 * `unreleased versions` or `unreleased Chrome versions`:
 109   alpha and beta versions.
 110 * `last 2 major versions` or `last 2 iOS major versions`:
 111   all minor/patch releases of last 2 major versions.
 112 * `since 2015` or `last 2 years`: all versions released since year 2015
 113   (also `since 2015-03` and `since 2015-03-10`).
 114 * `not ie <= 8`: exclude browsers selected by previous queries.
 115
 116 You can add `not ` to any query.
 117
 118 ### Debug
 119
 120 Run `npx browserslist` in project directory to see what browsers was selected
 121 by your queries.
 122
 123 ```sh
 124 $ npx browserslist
 125 and_chr 61
 126 and_ff 56
 127 and_qq 1.2
 128 and_uc 11.4
 129 android 56
 130 baidu 7.12
 131 bb 10
 132 chrome 62
 133 edge 16
 134 firefox 56
 135 ios_saf 11
 136 opera 48
 137 safari 11
 138 samsung 5
 139 ```
 140
 141 ### Notes
 142
 143 Browserslist works with separated versions of browsers.
 144 You should avoid queries like `Firefox > 0`.
 145
 146 Multiple criteria are combined as a boolean `OR`. A browser version must match
 147 at least one of the criteria to be selected.
 148
 149 All queries are based on the [Can I Use] support table,
 150 e.g. `last 3 iOS versions` might select `8.4, 9.2, 9.3` (mixed major and minor),
 151 whereas `last 3 Chrome versions` might select `50, 49, 48` (major only).
 152
 153 [`caniuse-lite/data/regions`]: https://github.com/ben-eb/caniuse-lite/tree/master/data/regions
 154 [two-letter country code]:     http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
 155 [custom usage data]:           #custom-usage-data
 156 [Can I Use]:                   http://caniuse.com/
 157
 158 ### Browsers
 159
 160 Names are case insensitive:
 161
 162 * `Android` for Android WebView.
 163 * `Baidu` for Baidu Browser.
 164 * `BlackBerry` or `bb` for Blackberry browser.
 165 * `Chrome` for Google Chrome.
 166 * `ChromeAndroid` or `and_chr` for Chrome for Android
 167 * `Edge` for Microsoft Edge.
 168 * `Electron` for Electron framework. It will be converted to Chrome version.
 169 * `Explorer` or `ie` for Internet Explorer.
 170 * `ExplorerMobile` or `ie_mob` for Internet Explorer Mobile.
 171 * `Firefox` or `ff` for Mozilla Firefox.
 172 * `FirefoxAndroid` or `and_ff` for Firefox for Android.
 173 * `iOS` or `ios_saf` for iOS Safari.
 174 * `Opera` for Opera.
 175 * `OperaMini` or `op_mini` for Opera Mini.
 176 * `OperaMobile` or `op_mob` for Opera Mobile.
 177 * `QQAndroid` or `and_qq` for QQ Browser for Android.
 178 * `Safari` for desktop Safari.
 179 * `Samsung` for Samsung Internet.
 180 * `UCAndroid` or `and_uc` for UC Browser for Android.
 181
 182 ## `package.json`
 183
 184 If you want to reduce config files in project root, you can specify
 185 browsers in `package.json` with `browserslist` key:
 186
 187 ```json
 188 {
 189   "private": true,
 190   "dependencies": {
 191     "autoprefixer": "^6.5.4"
 192   },
 193   "browserslist": [
 194     "> 1%",
 195     "last 2 versions"
 196   ]
 197 }
 198 ```
 199
 200 ## Config File
 201
 202 Browserslist config should be named `.browserslistrc` or `browserslist`
 203 and have browsers queries split by a new line. Comments starts with `#` symbol:
 204
 205 ```yaml
 206 # Browsers that we support
 207
 208 > 1%
 209 Last 2 versions
 210 IE 8 # sorry
 211 ```
 212
 213 Browserslist will check config in every directory in `path`.
 214 So, if tool process `app/styles/main.css`, you can put config to root,
 215 `app/` or `app/styles`.
 216
 217 You can specify direct path in `BROWSERSLIST_CONFIG` environment variables.
 218
 219 ## Shareable Configs
 220
 221 You can use the following query to reference an exported Browserslist config
 222 from another package:
 223
 224 ```json
 225   "browserslist": [
 226     "extends browserslist-config-mycompany"
 227   ]
 228 ```
 229
 230 For security reasons, external configuration only supports packages that have
 231 the `browserslist-config-` prefix. npm scoped packages are also supported, by
 232 naming or prefixing the module with `@scope/browserslist-config`, such as
 233 `@scope/browserslist-config` or `@scope/browserslist-config-mycompany`.
 234
 235 If you don’t accept Browserslist queries from users, you can disable the
 236 validation by using the `dangerousExtend` option:
 237
 238 ```js
 239 browserslist(queries, { path, dangerousExtend: true })
 240 ```
 241
 242 Because this uses `npm`'s resolution, you can also reference specific files
 243 in a package:
 244
 245 ```json
 246   "browserslist": [
 247     "extends browserslist-config-mycompany/desktop",
 248     "extends browserslist-config-mycompany/mobile"
 249   ]
 250 ```
 251
 252 When writing a shared Browserslist package, just export an array.
 253 `browserslist-config-mycompany/index.js`:
 254
 255 ```js
 256 module.exports = [
 257   'last 2 versions',
 258   'ie 9'
 259 ]
 260 ```
 261
 262 ## Environment Variables
 263
 264 If some tool use Browserslist inside, you can change browsers settings
 265 by [environment variables]:
 266
 267 * `BROWSERSLIST` with browsers queries.
 268
 269    ```sh
 270   BROWSERSLIST="> 5%" gulp css
 271    ```
 272
 273 * `BROWSERSLIST_CONFIG` with path to config file.
 274
 275    ```sh
 276   BROWSERSLIST_CONFIG=./config/browserslist gulp css
 277    ```
 278
 279 * `BROWSERSLIST_ENV` with environments string.
 280
 281    ```sh
 282   BROWSERSLIST_ENV="development" gulp css
 283    ```
 284
 285 * `BROWSERSLIST_STATS` with path to the custom usage data
 286   for `> 1% in my stats` query.
 287
 288    ```sh
 289   BROWSERSLIST_STATS=./config/usage_data.json gulp css
 290    ```
 291
 292 * `BROWSERSLIST_DISABLE_CACHE` if you want to disable config reading cache.
 293
 294    ```sh
 295   BROWSERSLIST_DISABLE_CACHE=1 gulp css
 296    ```
 297
 298 [environment variables]: https://en.wikipedia.org/wiki/Environment_variable
 299
 300 ## Environments
 301
 302 You can also specify different browser queries for various environments.
 303 Browserslist will choose query according to `BROWSERSLIST_ENV` or `NODE_ENV`
 304 variables. If none of them is declared, Browserslist will firstly look
 305 for `development` queries and then use defaults.
 306
 307 In `package.json`:
 308
 309 ```js
 310   "browserslist": {
 311     "production": [
 312       "last 2 version",
 313       "ie 9"
 314     ],
 315     "development": [
 316       "last 1 version"
 317     ]
 318   }
 319 ```
 320
 321 In `.browserslistrc` config:
 322
 323 ```ini
 324 [production]
 325 last 2 version
 326 ie 9
 327
 328 [development]
 329 last 1 version
 330 ```
 331
 332 ## Custom Usage Data
 333
 334 If you have a website, you can query against the usage statistics of your site:
 335
 336 1. Import your Google Analytics data into [Can I Use].
 337    Press `Import…` button in Settings page.
 338 2. Open browser DevTools on [Can I Use] and paste this snippet
 339    into the browser console:
 340
 341     ```js
 342    var e=document.createElement('a');e.setAttribute('href', 'data:text/plain;charset=utf-8,'+encodeURIComponent(JSON.stringify(JSON.parse(localStorage['usage-data-by-id'])[localStorage['config-primary_usage']])));e.setAttribute('download','stats.json');document.body.appendChild(e);e.click();document.body.removeChild(e);
 343     ```
 344 3. Save the data to a `browserslist-stats.json` file in your project.
 345
 346 Of course, you can generate usage statistics file by any other method.
 347 File format should be like:
 348
 349 ```js
 350 {
 351   "ie": {
 352     "6": 0.01,
 353     "7": 0.4,
 354     "8": 1.5
 355   },
 356   "chrome": {
 357     …
 358   },
 359   …
 360 }
 361 ```
 362
 363 Note that you can query against your custom usage data
 364 while also querying against global or regional data.
 365 For example, the query `> 1% in my stats, > 5% in US, 10%` is permitted.
 366
 367 [Can I Use]: http://caniuse.com/
 368
 369 ## Webpack
 370
 371 If you plan to use Browserslist on client-side (e. g., tools like CodePen)
 372 Browserslist could take big part of your bundle (150 KB).
 373
 374 But the biggest part of this size will be region usage statistics, which could
 375 be useless for you. `IgnorePlugin` could cut it:
 376
 377 ```js
 378 const webpackConfig = {
 379   …
 380   plugins: [
 381     new webpack.IgnorePlugin(/caniuse-lite\/data\/regions/)
 382   ]
 383 }
 384 ```
 385
 386 This plugin will reduce Browserslist size from 150 KB to 6 KB. But you loose
 387 `> 1% in US` queries support.
 388
 389 ## JS API
 390
 391 ```js
 392 var browserslist = require('browserslist');
 393
 394 // Your CSS/JS build tool code
 395 var process = function (source, opts) {
 396     var browsers = browserslist(opts.browsers, {
 397         stats: opts.stats,
 398         path:  opts.file,
 399         env:   opts.env
 400     });
 401     // Your code to add features for selected browsers
 402 }
 403 ```
 404
 405 Queries can be a string `"> 5%, last 1 version"`
 406 or an array `['> 5%', 'last 1 version']`.
 407
 408 If a query is missing, Browserslist will look for a config file.
 409 You can provide a `path` option (that can be a file) to find the config file
 410 relatively to it.
 411
 412 For non-JS environment and debug purpose you can use CLI tool:
 413
 414 ```sh
 415 browserslist "> 1%, last 2 versions"
 416 ```
 417
 418 ## Coverage
 419
 420 You can get total users coverage for selected browsers by JS API:
 421
 422 ```js
 423 browserslist.coverage(browserslist('> 1%')) //=> 81.4
 424 ```
 425
 426 ```js
 427 browserslist.coverage(browserslist('> 1% in US'), 'US') //=> 83.1
 428 ```
 429
 430 Or by CLI:
 431
 432 ```sh
 433 $ browserslist --coverage "> 1%"
 434 These browsers account for 81.4% of all users globally
 435 ```
 436
 437 ```sh
 438 $ browserslist --coverage=US "> 1% in US"
 439 These browsers account for 83.1% of all users in the US
 440 ```
 441
 442 ## Cache
 443
 444 Browserslist caches the configuration it reads from `package.json` and
 445 `browserslist` files, as well as knowledge about the existence of files,
 446 for the duration of the hosting process.
 447
 448 To clear these caches, use:
 449
 450 ```js
 451 browserslist.clearCaches();
 452 ```
 453
 454 To disable the caching altogether, set the `BROWSERSLIST_DISABLE_CACHE`
 455 environment variable.