1 | # Browserslist [![Cult Of Martians][cult-img]][cult]
|
2 |
|
3 | <img width="120" height="120" alt="Browserslist logo by Anton Lovchikov"
|
4 | src="https://browserslist.github.io/browserslist/logo.svg" align="right">
|
5 |
|
6 | The config to share target browsers and Node.js versions between different
|
7 | front-end tools. It is used in:
|
8 |
|
9 | * [Autoprefixer]
|
10 | * [Babel]
|
11 | * [postcss-preset-env]
|
12 | * [eslint-plugin-compat]
|
13 | * [stylelint-no-unsupported-browser-features]
|
14 | * [postcss-normalize]
|
15 | * [obsolete-webpack-plugin]
|
16 |
|
17 | All tools will find target browsers automatically,
|
18 | when you add the following to `package.json`:
|
19 |
|
20 | ```json
|
21 | "browserslist": [
|
22 | "defaults",
|
23 | "not IE 11",
|
24 | "maintained node versions"
|
25 | ]
|
26 | ```
|
27 |
|
28 | Or in `.browserslistrc` config:
|
29 |
|
30 | ```yaml
|
31 | # Browsers that we support
|
32 |
|
33 | defaults
|
34 | not IE 11
|
35 | maintained node versions
|
36 | ```
|
37 |
|
38 | Developers set their version lists using queries like `last 2 versions`
|
39 | to be free from updating versions manually.
|
40 | Browserslist will use [`caniuse-lite`] with [Can I Use] data for this queries.
|
41 |
|
42 | Browserslist will take queries from tool option,
|
43 | `browserslist` config, `.browserslistrc` config,
|
44 | `browserslist` section in `package.json` or environment variables.
|
45 |
|
46 | [cult-img]: https://cultofmartians.com/assets/badges/badge.svg
|
47 | [cult]: https://cultofmartians.com/done.html
|
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" width="236" height="54">
|
52 | </a>
|
53 |
|
54 | [stylelint-no-unsupported-browser-features]: https://github.com/ismay/stylelint-no-unsupported-browser-features
|
55 | [eslint-plugin-compat]: https://github.com/amilajack/eslint-plugin-compat
|
56 | [Browserslist Example]: https://github.com/browserslist/browserslist-example
|
57 | [postcss-preset-env]: https://github.com/jonathantneal/postcss-preset-env
|
58 | [postcss-normalize]: https://github.com/jonathantneal/postcss-normalize
|
59 | [`caniuse-lite`]: https://github.com/ben-eb/caniuse-lite
|
60 | [Autoprefixer]: https://github.com/postcss/autoprefixer
|
61 | [Can I Use]: https://caniuse.com/
|
62 | [Babel]: https://github.com/babel/babel/tree/master/packages/babel-preset-env
|
63 | [obsolete-webpack-plugin]: https://github.com/ElemeFE/obsolete-webpack-plugin
|
64 |
|
65 | ## Table of Contents
|
66 |
|
67 | * [Tools](#tools)
|
68 | * [Text Editors](#text-editors)
|
69 | * [Best Practices](#best-practices)
|
70 | * [Browsers Data Updating](#browsers-data-updating)
|
71 | * [Queries](#queries)
|
72 | * [Query Composition](#query-composition)
|
73 | * [Full List](#full-list)
|
74 | * [Debug](#debug)
|
75 | * [Browsers](#browsers)
|
76 | * [Config File](#config-file)
|
77 | * [`package.json`](#packagejson)
|
78 | * [`.browserslistrc`](#browserslistrc)
|
79 | * [Shareable Configs](#shareable-configs)
|
80 | * [Configuring for Different Environments](#configuring-for-different-environments)
|
81 | * [Custom Usage Data](#custom-usage-data)
|
82 | * [JS API](#js-api)
|
83 | * [Environment Variables](#environment-variables)
|
84 | * [Cache](#cache)
|
85 | * [Security Contact](#security-contact)
|
86 | * [For Enterprise](#for-enterprise)
|
87 |
|
88 | ## Tools
|
89 |
|
90 | * [`browserl.ist`](https://browserl.ist/) is an online tool to check
|
91 | what browsers will be selected by some query.
|
92 | * [`browserslist-ga`] and [`browserslist-ga-export`] download your website
|
93 | browsers statistics to use it in `> 0.5% in my stats` query.
|
94 | * [`browserslist-useragent-regexp`] compiles Browserslist query to a RegExp
|
95 | to test browser useragent.
|
96 | * [`browserslist-useragent-ruby`] is a Ruby library to checks browser
|
97 | by user agent string to match Browserslist.
|
98 | * [`browserslist-browserstack`] runs BrowserStack tests for all browsers
|
99 | in Browserslist config.
|
100 | * [`browserslist-adobe-analytics`] use Adobe Analytics data to target browsers.
|
101 | * [`caniuse-api`] returns browsers which support some specific feature.
|
102 | * Run `npx browserslist` in your project directory to see project’s
|
103 | target browsers. This CLI tool is built-in and available in any project
|
104 | with Autoprefixer.
|
105 |
|
106 | [`browserslist-useragent-regexp`]: https://github.com/browserslist/browserslist-useragent-regexp
|
107 | [`browserslist-adobe-analytics`]: https://github.com/xeroxinteractive/browserslist-adobe-analytics
|
108 | [`browserslist-useragent-ruby`]: https://github.com/browserslist/browserslist-useragent-ruby
|
109 | [`browserslist-browserstack`]: https://github.com/xeroxinteractive/browserslist-browserstack
|
110 | [`browserslist-ga-export`]: https://github.com/browserslist/browserslist-ga-export
|
111 | [`browserslist-useragent`]: https://github.com/pastelsky/browserslist-useragent
|
112 | [`browserslist-ga`]: https://github.com/browserslist/browserslist-ga
|
113 | [`caniuse-api`]: https://github.com/Nyalab/caniuse-api
|
114 |
|
115 |
|
116 | ### Text Editors
|
117 |
|
118 | These extensions will add syntax highlighting for `.browserslistrc` files.
|
119 |
|
120 | * [VS Code](https://marketplace.visualstudio.com/items?itemName=webben.browserslist)
|
121 | * [Vim](https://github.com/browserslist/vim-browserslist)
|
122 |
|
123 | ## Best Practices
|
124 |
|
125 | * There is a `defaults` query, which gives a reasonable configuration
|
126 | for most users:
|
127 |
|
128 | ```json
|
129 | "browserslist": [
|
130 | "defaults"
|
131 | ]
|
132 | ```
|
133 |
|
134 | * If you want to change the default set of browsers, we recommend combining
|
135 | `last 2 versions`, `not dead` with a usage number like `> 0.2%`. This is
|
136 | because `last n versions` on its own does not add popular old versions, while
|
137 | only using a percentage above `0.2%` will in the long run make popular
|
138 | browsers even more popular. We might run into a monopoly and stagnation
|
139 | situation, as we had with Internet Explorer 6. Please use this setting
|
140 | with caution.
|
141 | * Select browsers directly (`last 2 Chrome versions`) only if you are making
|
142 | a web app for a kiosk with one browser. There are a lot of browsers
|
143 | on the market. If you are making general web app you should respect
|
144 | browsers diversity.
|
145 | * Don’t remove browsers just because you don’t know them. Opera Mini has
|
146 | 100 million users in Africa and it is more popular in the global market
|
147 | than Microsoft Edge. Chinese QQ Browsers has more market share than Firefox
|
148 | and desktop Safari combined.
|
149 |
|
150 |
|
151 | ## Browsers Data Updating
|
152 |
|
153 | `npx browserslist@latest --update-db` updates `caniuse-lite` version
|
154 | in your npm, yarn or pnpm lock file.
|
155 |
|
156 | You need to do it regularly for two reasons:
|
157 |
|
158 | 1. To use the latest browser’s versions and statistics in queries like
|
159 | `last 2 versions` or `>1%`. For example, if you created your project
|
160 | 2 years ago and did not update your dependencies, `last 1 version`
|
161 | will return 2 year old browsers.
|
162 | 2. `caniuse-lite` deduplication: to synchronize version in different tools.
|
163 |
|
164 | > What is deduplication?
|
165 |
|
166 | Due to how npm architecture is setup, you may have a situation
|
167 | where you have multiple versions of a single dependency required.
|
168 |
|
169 | Imagine you begin a project, and you add `autoprefixer` as a dependency.
|
170 | npm looks for the latest `caniuse-lite` version (1.0.30000700) and adds it to
|
171 | `package-lock.json` under `autoprefixer` dependencies.
|
172 |
|
173 | A year later, you decide to add Babel. At this moment, we have a
|
174 | new version of `canuse-lite` (1.0.30000900). npm took the latest version
|
175 | and added it to your lock file under `@babel/preset-env` dependencies.
|
176 |
|
177 | Now your lock file looks like this:
|
178 |
|
179 | ```ocaml
|
180 | autoprefixer 7.1.4
|
181 | browserslist 3.1.1
|
182 | caniuse-lite 1.0.30000700
|
183 | @babel/preset-env 7.10.0
|
184 | browserslist 4.13.0
|
185 | caniuse-lite 1.0.30000900
|
186 | ```
|
187 |
|
188 | As you can see, we now have two versions of `caniuse-lite` installed.
|
189 |
|
190 |
|
191 | ## Queries
|
192 |
|
193 | Browserslist will use browsers and Node.js versions query
|
194 | from one of these sources:
|
195 |
|
196 | 1. `browserslist` key in `package.json` file in current or parent directories.
|
197 | **We recommend this way.**
|
198 | 2. `.browserslistrc` config file in current or parent directories.
|
199 | 3. `browserslist` config file in current or parent directories.
|
200 | 4. `BROWSERSLIST` environment variable.
|
201 | 5. If the above methods did not produce a valid result
|
202 | Browserslist will use defaults:
|
203 | `> 0.5%, last 2 versions, Firefox ESR, not dead`.
|
204 |
|
205 |
|
206 | ### Query Composition
|
207 |
|
208 | An `or` combiner can use the keyword `or` as well as `,`.
|
209 | `last 1 version or > 1%` is equal to `last 1 version, > 1%`.
|
210 |
|
211 | `and` query combinations are also supported to perform an
|
212 | intersection of all the previous queries:
|
213 | `last 1 version or chrome > 75 and > 1%` will select
|
214 | (`browser last version` or `Chrome since 76`) and `more than 1% marketshare`.
|
215 |
|
216 | There is 3 different ways to combine queries as depicted below. First you start
|
217 | with a single query and then we combine the queries to get our final list.
|
218 |
|
219 | Obviously you can *not* start with a `not` combiner, since there is no left-hand
|
220 | side query to combine it with. The left-hand is always resolved as `and`
|
221 | combiner even if `or` is used (this is an API implementation specificity).
|
222 |
|
223 | | Query combiner type | Illustration | Example |
|
224 | | ------------------- | :----------: | ------- |
|
225 | |`or`/`,` combiner <br> (union) | ![Union of queries](img/union.svg) | `> .5% or last 2 versions` <br> `> .5%, last 2 versions` |
|
226 | | `and` combiner <br> (intersection) | ![intersection of queries](img/intersection.svg) | `> .5% and last 2 versions` |
|
227 | | `not` combiner <br> (relative complement) | ![Relative complement of queries](img/complement.svg) | All those three are equivalent to the first one <br> `> .5% and not last 2 versions` <br> `> .5% or not last 2 versions` <br> `> .5%, not last 2 versions` |
|
228 |
|
229 | _A quick way to test your query is to do `npx browserslist '> 0.5%, not IE 11'`
|
230 | in your terminal._
|
231 |
|
232 | ### Full List
|
233 |
|
234 | You can specify the browser and Node.js versions by queries (case insensitive):
|
235 |
|
236 | * `defaults`: Browserslist’s default browsers
|
237 | (`> 0.5%, last 2 versions, Firefox ESR, not dead`).
|
238 | * `> 5%`: browsers versions selected by global usage statistics.
|
239 | `>=`, `<` and `<=` work too.
|
240 | * `> 5% in US`: uses USA usage statistics.
|
241 | It accepts [two-letter country code].
|
242 | * `> 5% in alt-AS`: uses Asia region usage statistics.
|
243 | List of all region codes can be found at [`caniuse-lite/data/regions`].
|
244 | * `> 5% in my stats`: uses [custom usage data].
|
245 | * `> 5% in browserslist-config-mycompany stats`: uses [custom usage data]
|
246 | from `browserslist-config-mycompany/browserslist-stats.json`.
|
247 | * `cover 99.5%`: most popular browsers that provide coverage.
|
248 | * `cover 99.5% in US`: same as above, with [two-letter country code].
|
249 | * `cover 99.5% in my stats`: uses [custom usage data].
|
250 | * `dead`: browsers without official support or updates for 24 months.
|
251 | Right now it is `IE 10`, `IE_Mob 11`, `BlackBerry 10`, `BlackBerry 7`,
|
252 | `Samsung 4` and `OperaMobile 12.1`.
|
253 | * `last 2 versions`: the last 2 versions for *each* browser.
|
254 | * `last 2 Chrome versions`: the last 2 versions of Chrome browser.
|
255 | * `last 2 major versions` or `last 2 iOS major versions`:
|
256 | all minor/patch releases of last 2 major versions.
|
257 | * `node 10` and `node 10.4`: selects latest Node.js `10.x.x`
|
258 | or `10.4.x` release.
|
259 | * `current node`: Node.js version used by Browserslist right now.
|
260 | * `maintained node versions`: all Node.js versions, which are [still maintained]
|
261 | by Node.js Foundation.
|
262 | * `iOS 7`: the iOS browser version 7 directly.
|
263 | * `Firefox > 20`: versions of Firefox newer than 20.
|
264 | `>=`, `<` and `<=` work too. It also works with Node.js.
|
265 | * `ie 6-8`: selects an inclusive range of versions.
|
266 | * `Firefox ESR`: the latest [Firefox Extended Support Release].
|
267 | * `PhantomJS 2.1` and `PhantomJS 1.9`: selects Safari versions similar
|
268 | to PhantomJS runtime.
|
269 | * `extends browserslist-config-mycompany`: take queries from
|
270 | `browserslist-config-mycompany` npm package.
|
271 | * `supports es6-module`: browsers with support for specific features.
|
272 | `es6-module` here is the `feat` parameter at the URL of the [Can I Use]
|
273 | page. A list of all available features can be found at
|
274 | [`caniuse-lite/data/features`].
|
275 | * `browserslist config`: the browsers defined in Browserslist config. Useful
|
276 | in Differential Serving to modify user’s config like
|
277 | `browserslist config and supports es6-module`.
|
278 | * `since 2015` or `last 2 years`: all versions released since year 2015
|
279 | (also `since 2015-03` and `since 2015-03-10`).
|
280 | * `unreleased versions` or `unreleased Chrome versions`:
|
281 | alpha and beta versions.
|
282 | * `not ie <= 8`: exclude IE 8 and lower from previous queries.
|
283 |
|
284 | You can add `not ` to any query.
|
285 |
|
286 | [`caniuse-lite/data/regions`]: https://github.com/ben-eb/caniuse-lite/tree/master/data/regions
|
287 | [`caniuse-lite/data/features`]: https://github.com/ben-eb/caniuse-lite/tree/master/data/features
|
288 | [two-letter country code]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
|
289 | [custom usage data]: #custom-usage-data
|
290 | [still maintained]: https://github.com/nodejs/Release
|
291 | [Can I Use]: https://caniuse.com/
|
292 | [Firefox Extended Support Release]: https://support.mozilla.org/en-US/kb/choosing-firefox-update-channel
|
293 |
|
294 |
|
295 | ### Debug
|
296 |
|
297 | Run `npx browserslist` in project directory to see what browsers was selected
|
298 | by your queries.
|
299 |
|
300 | ```sh
|
301 | $ npx browserslist
|
302 | and_chr 61
|
303 | and_ff 56
|
304 | and_qq 1.2
|
305 | and_uc 11.4
|
306 | android 56
|
307 | baidu 7.12
|
308 | bb 10
|
309 | chrome 62
|
310 | edge 16
|
311 | firefox 56
|
312 | ios_saf 11
|
313 | opera 48
|
314 | safari 11
|
315 | samsung 5
|
316 | ```
|
317 |
|
318 |
|
319 | ### Browsers
|
320 |
|
321 | Names are case insensitive:
|
322 |
|
323 | * `Android` for Android WebView.
|
324 | * `Baidu` for Baidu Browser.
|
325 | * `BlackBerry` or `bb` for Blackberry browser.
|
326 | * `Chrome` for Google Chrome.
|
327 | * `ChromeAndroid` or `and_chr` for Chrome for Android
|
328 | * `Edge` for Microsoft Edge.
|
329 | * `Electron` for Electron framework. It will be converted to Chrome version.
|
330 | * `Explorer` or `ie` for Internet Explorer.
|
331 | * `ExplorerMobile` or `ie_mob` for Internet Explorer Mobile.
|
332 | * `Firefox` or `ff` for Mozilla Firefox.
|
333 | * `FirefoxAndroid` or `and_ff` for Firefox for Android.
|
334 | * `iOS` or `ios_saf` for iOS Safari.
|
335 | * `Node` for Node.js.
|
336 | * `Opera` for Opera.
|
337 | * `OperaMini` or `op_mini` for Opera Mini.
|
338 | * `OperaMobile` or `op_mob` for Opera Mobile.
|
339 | * `QQAndroid` or `and_qq` for QQ Browser for Android.
|
340 | * `Safari` for desktop Safari.
|
341 | * `Samsung` for Samsung Internet.
|
342 | * `UCAndroid` or `and_uc` for UC Browser for Android.
|
343 | * `kaios` for KaiOS Browser.
|
344 |
|
345 |
|
346 | ## Config File
|
347 |
|
348 | ### `package.json`
|
349 |
|
350 | If you want to reduce config files in project root, you can specify
|
351 | browsers in `package.json` with `browserslist` key:
|
352 |
|
353 | ```json
|
354 | {
|
355 | "private": true,
|
356 | "dependencies": {
|
357 | "autoprefixer": "^6.5.4"
|
358 | },
|
359 | "browserslist": [
|
360 | "last 1 version",
|
361 | "> 1%",
|
362 | "IE 10"
|
363 | ]
|
364 | }
|
365 | ```
|
366 |
|
367 |
|
368 | ### `.browserslistrc`
|
369 |
|
370 | Separated Browserslist config should be named `.browserslistrc`
|
371 | and have browsers queries split by a new line.
|
372 | Each line is combined with the `or` combiner. Comments starts with `#` symbol:
|
373 |
|
374 | ```yaml
|
375 | # Browsers that we support
|
376 |
|
377 | last 1 version
|
378 | > 1%
|
379 | IE 10 # sorry
|
380 | ```
|
381 |
|
382 | Browserslist will check config in every directory in `path`.
|
383 | So, if tool process `app/styles/main.css`, you can put config to root,
|
384 | `app/` or `app/styles`.
|
385 |
|
386 | You can specify direct path in `BROWSERSLIST_CONFIG` environment variables.
|
387 |
|
388 |
|
389 | ## Shareable Configs
|
390 |
|
391 | You can use the following query to reference an exported Browserslist config
|
392 | from another package:
|
393 |
|
394 | ```json
|
395 | "browserslist": [
|
396 | "extends browserslist-config-mycompany"
|
397 | ]
|
398 | ```
|
399 |
|
400 | For security reasons, external configuration only supports packages that have
|
401 | the `browserslist-config-` prefix. npm scoped packages are also supported, by
|
402 | naming or prefixing the module with `@scope/browserslist-config`, such as
|
403 | `@scope/browserslist-config` or `@scope/browserslist-config-mycompany`.
|
404 |
|
405 | If you don’t accept Browserslist queries from users, you can disable the
|
406 | validation by using the or `BROWSERSLIST_DANGEROUS_EXTEND` environment variable.
|
407 |
|
408 | ```sh
|
409 | BROWSERSLIST_DANGEROUS_EXTEND=1 npx webpack
|
410 | ```
|
411 |
|
412 | Because this uses `npm`'s resolution, you can also reference specific files
|
413 | in a package:
|
414 |
|
415 | ```json
|
416 | "browserslist": [
|
417 | "extends browserslist-config-mycompany/desktop",
|
418 | "extends browserslist-config-mycompany/mobile"
|
419 | ]
|
420 | ```
|
421 |
|
422 | When writing a shared Browserslist package, just export an array.
|
423 | `browserslist-config-mycompany/index.js`:
|
424 |
|
425 | ```js
|
426 | module.exports = [
|
427 | 'last 1 version',
|
428 | '> 1%',
|
429 | 'ie 10'
|
430 | ]
|
431 | ```
|
432 |
|
433 | You can also include a `browserslist-stats.json` file as part of your shareable
|
434 | config at the root and query it using
|
435 | `> 5% in browserslist-config-mycompany stats`. It uses the same format
|
436 | as `extends` and the `dangerousExtend` property as above.
|
437 |
|
438 | You can export configs for different environments and select environment
|
439 | by `BROWSERSLIST_ENV` or `env` option in your tool:
|
440 |
|
441 | ```js
|
442 | module.exports = {
|
443 | development: [
|
444 | 'last 1 version'
|
445 | ],
|
446 | production: [
|
447 | 'last 1 version',
|
448 | '> 1%',
|
449 | 'ie 10'
|
450 | ]
|
451 | }
|
452 | ```
|
453 |
|
454 |
|
455 | ## Configuring for Different Environments
|
456 |
|
457 | You can also specify different browser queries for various environments.
|
458 | Browserslist will choose query according to `BROWSERSLIST_ENV` or `NODE_ENV`
|
459 | variables. If none of them is declared, Browserslist will firstly look
|
460 | for `production` queries and then use defaults.
|
461 |
|
462 | In `package.json`:
|
463 |
|
464 | ```js
|
465 | "browserslist": {
|
466 | "production": [
|
467 | "> 1%",
|
468 | "ie 10"
|
469 | ],
|
470 | "modern": [
|
471 | "last 1 chrome version",
|
472 | "last 1 firefox version"
|
473 | ],
|
474 | "ssr": [
|
475 | "node 12"
|
476 | ]
|
477 | }
|
478 | ```
|
479 |
|
480 | In `.browserslistrc` config:
|
481 |
|
482 | ```ini
|
483 | [production]
|
484 | > 1%
|
485 | ie 10
|
486 |
|
487 | [modern]
|
488 | last 1 chrome version
|
489 | last 1 firefox version
|
490 |
|
491 | [ssr]
|
492 | node 12
|
493 | ```
|
494 |
|
495 |
|
496 | ## Custom Usage Data
|
497 |
|
498 | If you have a website, you can query against the usage statistics of your site.
|
499 | [`browserslist-ga`] will ask access to Google Analytics and then generate
|
500 | `browserslist-stats.json`:
|
501 |
|
502 | ```
|
503 | npx browserslist-ga
|
504 | ```
|
505 |
|
506 | Or you can use [`browserslist-ga-export`] to convert Google Analytics data without giving a password for Google account.
|
507 |
|
508 | You can generate usage statistics file by any other method. File format should
|
509 | be like:
|
510 |
|
511 | ```js
|
512 | {
|
513 | "ie": {
|
514 | "6": 0.01,
|
515 | "7": 0.4,
|
516 | "8": 1.5
|
517 | },
|
518 | "chrome": {
|
519 | …
|
520 | },
|
521 | …
|
522 | }
|
523 | ```
|
524 |
|
525 | Note that you can query against your custom usage data while also querying
|
526 | against global or regional data. For example, the query
|
527 | `> 1% in my stats, > 5% in US, 10%` is permitted.
|
528 |
|
529 | [`browserslist-ga-export`]: https://github.com/browserslist/browserslist-ga-export
|
530 | [`browserslist-ga`]: https://github.com/browserslist/browserslist-ga
|
531 | [Can I Use]: https://caniuse.com/
|
532 |
|
533 |
|
534 | ## JS API
|
535 |
|
536 | ```js
|
537 | const browserslist = require('browserslist')
|
538 |
|
539 | // Your CSS/JS build tool code
|
540 | function process (source, opts) {
|
541 | const browsers = browserslist(opts.overrideBrowserslist, {
|
542 | stats: opts.stats,
|
543 | path: opts.file,
|
544 | env: opts.env
|
545 | })
|
546 | // Your code to add features for selected browsers
|
547 | }
|
548 | ```
|
549 |
|
550 | Queries can be a string `"> 1%, IE 10"`
|
551 | or an array `['> 1%', 'IE 10']`.
|
552 |
|
553 | If a query is missing, Browserslist will look for a config file.
|
554 | You can provide a `path` option (that can be a file) to find the config file
|
555 | relatively to it.
|
556 |
|
557 | Options:
|
558 |
|
559 | * `path`: file or a directory path to look for config file. Default is `.`.
|
560 | * `env`: what environment section use from config. Default is `production`.
|
561 | * `stats`: custom usage statistics data.
|
562 | * `config`: path to config if you want to set it manually.
|
563 | * `ignoreUnknownVersions`: do not throw on direct query (like `ie 12`).
|
564 | Default is `false`.
|
565 | * `dangerousExtend`: Disable security checks for `extend` query.
|
566 | Default is `false`.
|
567 | * `mobileToDesktop`: Use desktop browsers if Can I Use doesn’t have data
|
568 | about this mobile version. For instance, Browserslist will return
|
569 | `chrome 20` on `and_chr 20` query (Can I Use has only data only about
|
570 | latest versions of mobile browsers). Default is `false`.
|
571 |
|
572 | For non-JS environment and debug purpose you can use CLI tool:
|
573 |
|
574 | ```sh
|
575 | browserslist "> 1%, IE 10"
|
576 | ```
|
577 |
|
578 | You can get total users coverage for selected browsers by JS API:
|
579 |
|
580 | ```js
|
581 | browserslist.coverage(browserslist('> 1%'))
|
582 | //=> 81.4
|
583 | ```
|
584 |
|
585 | ```js
|
586 | browserslist.coverage(browserslist('> 1% in US'), 'US')
|
587 | //=> 83.1
|
588 | ```
|
589 |
|
590 | ```js
|
591 | browserslist.coverage(browserslist('> 1% in my stats'), 'my stats')
|
592 | //=> 83.1
|
593 | ```
|
594 |
|
595 | ```js
|
596 | browserslist.coverage(browserslist('> 1% in my stats', { stats }), stats)
|
597 | //=> 82.2
|
598 | ```
|
599 |
|
600 | Or by CLI:
|
601 |
|
602 | ```sh
|
603 | $ browserslist --coverage "> 1%"
|
604 | These browsers account for 81.4% of all users globally
|
605 | ```
|
606 |
|
607 | ```sh
|
608 | $ browserslist --coverage=US "> 1% in US"
|
609 | These browsers account for 83.1% of all users in the US
|
610 | ```
|
611 |
|
612 | ```sh
|
613 | $ browserslist --coverage "> 1% in my stats"
|
614 | These browsers account for 83.1% of all users in custom statistics
|
615 | ```
|
616 |
|
617 | ```sh
|
618 | $ browserslist --coverage "> 1% in my stats" --stats=./stats.json
|
619 | These browsers account for 83.1% of all users in custom statistics
|
620 | ```
|
621 |
|
622 |
|
623 | ## Environment Variables
|
624 |
|
625 | If a tool uses Browserslist inside, you can change the Browserslist settings
|
626 | with [environment variables]:
|
627 |
|
628 | * `BROWSERSLIST` with browsers queries.
|
629 |
|
630 | ```sh
|
631 | BROWSERSLIST="> 5%" npx webpack
|
632 | ```
|
633 |
|
634 | * `BROWSERSLIST_CONFIG` with path to config file.
|
635 |
|
636 | ```sh
|
637 | BROWSERSLIST_CONFIG=./config/browserslist npx webpack
|
638 | ```
|
639 |
|
640 | * `BROWSERSLIST_ENV` with environments string.
|
641 |
|
642 | ```sh
|
643 | BROWSERSLIST_ENV="development" npx webpack
|
644 | ```
|
645 |
|
646 | * `BROWSERSLIST_STATS` with path to the custom usage data
|
647 | for `> 1% in my stats` query.
|
648 |
|
649 | ```sh
|
650 | BROWSERSLIST_STATS=./config/usage_data.json npx webpack
|
651 | ```
|
652 |
|
653 | * `BROWSERSLIST_DISABLE_CACHE` if you want to disable config reading cache.
|
654 |
|
655 | ```sh
|
656 | BROWSERSLIST_DISABLE_CACHE=1 npx webpack
|
657 | ```
|
658 |
|
659 | * `BROWSERSLIST_DANGEROUS_EXTEND` to disable security shareable config
|
660 | name check.
|
661 |
|
662 | ```sh
|
663 | BROWSERSLIST_DANGEROUS_EXTEND=1 npx webpack
|
664 | ```
|
665 |
|
666 | [environment variables]: https://en.wikipedia.org/wiki/Environment_variable
|
667 |
|
668 |
|
669 | ## Cache
|
670 |
|
671 | Browserslist caches the configuration it reads from `package.json` and
|
672 | `browserslist` files, as well as knowledge about the existence of files,
|
673 | for the duration of the hosting process.
|
674 |
|
675 | To clear these caches, use:
|
676 |
|
677 | ```js
|
678 | browserslist.clearCaches()
|
679 | ```
|
680 |
|
681 | To disable the caching altogether, set the `BROWSERSLIST_DISABLE_CACHE`
|
682 | environment variable.
|
683 |
|
684 |
|
685 | ## Security Contact
|
686 |
|
687 | To report a security vulnerability, please use the [Tidelift security contact].
|
688 | Tidelift will coordinate the fix and disclosure.
|
689 |
|
690 | [Tidelift security contact]: https://tidelift.com/security
|
691 |
|
692 |
|
693 | ## For Enterprise
|
694 |
|
695 | Available as part of the Tidelift Subscription.
|
696 |
|
697 | The maintainers of `browserslist` and thousands of other packages are working
|
698 | with Tidelift to deliver commercial support and maintenance for the open source
|
699 | dependencies you use to build your applications. Save time, reduce risk,
|
700 | and improve code health, while paying the maintainers of the exact dependencies
|
701 | you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-browserslist?utm_source=npm-browserslist&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
|