There is no better summary, I feel that the official document has been written clearly enough, the translation is not good, please correct it

Introduction to the

Browserslist is a configuration tool that shares target browsers and Node versions between different front-end tools. It is mainly used by the following tools:

  • Autoprefixer
  • Babel
  • post-preset-env
  • eslint-plugin-compat
  • stylelint-unsupported-browser-features
  • postcss-normalize

The Browserslist example demonstrates how browserslist is used by each of the tools listed above. All tools will automatically find the target browser range of the current project plan, if you add the following configuration to the package.json of the front-end project:

{
  "browserslist": [
    "last 1 version",
    "> 1%",
    "maintained node versions",
    "not dead"
  ]
}
Copy the code

Browserslistrc configuration file:

Last 1 version > 1% maintained node versions not deadCopy the code

The developer can set the browser version query range (eg. Last 2 versions) so that the developer does not need to manually update the browser version frequently. Browserslist uses data from the Can I Use web site to query browser version ranges.

Browserslist provides an online query practice site that will be used next, click here to go.

Browserslist is a derivative tool

  • Browserja-ga: This tool generates version distribution data for browsers visiting your site for use in queries like > 0.5% in My Stats, provided you’re running a site with Google Analytics deployed.

  • Browserslist – userAgent: verifies that a browser’s user-agent string matches the browser scope given by Browserslist.

  • Browserslist-useragent-ruby: Same as above, Ruby library.

  • Caniuse-api: Returns the browser version range that supports the specified feature

  • NPX browserslist: Run the above command in the front-end project directory to output a list of target browsers for the current project.

Query source

Browserslist will restrict the browser and Node version range using the following configuration files:

  1. Tools Options, such as the Browsers property in the Autoprefixer tool configuration.
  2. BROWSERSLISTEnvironment variables.
  3. Current directory or a parent directorybrowserslistConfiguration file.
  4. Current directory or a parent directorybrowserslistrcConfiguration file.
  5. Current directory or a parent directorypackage.jsonIn the configuration filebrowserslistConfiguration item (recommended).
  6. Browserslist will use the default configuration if the above configuration file is missing or if other factors fail to generate a valid configuration> 0.5%, last 2 versions, Firefox ESR, not dead.

Best practices

  • This should only be used if you are developing web apps like kiosks on a specific browserlast 2 Chrome versionsTo target specific browser brands and versions. There are a lot of different browsers out there, and browser versions are very fragmented. If you’re developing a universal WebApp, you should consider compatibility issues caused by browser diversity.
  • If you don’t want to use browserslsit’s default Settings, it’s recommendedlast 1 version.not dead 和 > 0.2%(or> 1% in US.> 1% in my stats). Use onlylast n versionsAdding too many obsolete browsers to the project and not effectively covering older browsers that still have a high occupancy rate. Just > 0.2% make popular browsers even more popular, so we will have a monopoly and recession, As we had with Internet Explorer 6.
  • Don’t remove some browsers because you don’t know their distribution. Opera Mini has 100 million users in Africa and is more popular worldwide than Microsoft’s Edge browser. The QQ browser is used more than firefox and Safari on the desktop combined.

List of Query conditions

You can use the following query criteria to limit the browser and Node version range (case insensitive) :

  • > 5%: Browser version range selected based on global usage statistics.> =.<.< =The same applies.
  • > 5% in US: Same as above, only the locale is changed to the United States. Supports two – letter country codes to specify regions.
  • > 5% in alt-AS: same as above, only use region to change to all Countries in Asia.hereAll area codes are enumerated.
  • > 5% in my statsUse:Custom browser statistics.
  • Cover 99.5%: A browser version with 99.5% total usage, provided that the browser provides usage coverage.
  • Cover 99.5% in US: same as above, only limited geographical, support two letter country code.
  • Cover 99.5% in my statsUse:Custom browser statistics.
  • maintained node versions: All versions of Node still maintained by the Node Foundation.
  • node 10 and The node 10.4: Latest version of Node 10.x.x or 10.4.x.
  • current node: Specifies the node version currently used by Browserslist.
  • extends browserslist-config-mycompany: query Settings from the Browserslist-config-myCompany package
  • ie 6-8: Select a browser version range.
  • Firefox > 20: All Versions of Firefox older than 20.> =.<.< =The same applies.
  • ios 7: Ios 7 comes with a browser.
  • Firefox ESR: latest version of Firefox ESR (Long Term Support) browser.
  • unreleased versions or unreleased Chrome versions: Alpha and beta.
  • last 2 major versions or last 2 ios major versions: The last two releases, including all browser versions with minor and patch version changes.
  • since 2015 or last 2 years: The version that has been updated since a certain time (you can also write more specificallysince 2015-03orsince 2015-03-10)
  • deadThrough:last 2 versionsFiltered browser versions that have a global usage of less than 0.5% and are officially out of maintenance or have not actually been updated for two years. Currently eligible areIE10.IE_Mob 10.BlackBerry 10.BlackBerry 7.OperaMobile 12.1.
  • last 2 versions: The last two versions of each browser.
  • last 2 Chrome versions: Two recent versions of chrome.
  • defaults: Default configuration> 0.5%, last 2 versions, Firefox ESR, not dead.
  • not ie <= 8: invert the browser scope.
  • You can addnotThe value before any and query conditions is negative

Debug

Run NPX Browserslist directly in your project directory to see the range of browser versions that your filters filter out.

$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 5Copy the code

Matters needing attention

Browserslist handles every version of the browser, so you should avoid setting Firefox > 0 as a query.

When groups of query criteria are added together, they are overwritten as OR, not as AND, as long as the browser version matches one of the filter criteria.

All query criteria are based on the Can I Use support list. Such as: The last 3 ios versions may return 8.4, 9.2, 9.3(mixing major and minor versions), whereas the last 3 Chrome versions may return 50, 49, 48 (only major versions), In general, the browser version data collected by CanIUse will prevail.

Browser classification (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.

package.json

If you want to reduce the number of configuration files in the project root directory, you can set the browserslist configuration item in package.json, as shown below:

{
  "private": true."dependencies": {
    "autoprefixer": "^ 6.5.4"
  },
  "browserslist": [
    "last 1 version"."1%" >."IE 10"]}Copy the code

The configuration file

The Browserslist configuration file should be named.browserslistrc or Browserslist with a single line for each query. Comments begin with # :

# Browsers that we support

last 1 version
> 1%
IE 10 # sorry
Copy the code

Browserslist checks for configuration files at each level of the path. So, if the tool is working with a file path like app/styles/main.css, you can put the configuration file in the root directory, app/ or app/styles.

You can also specify the path to the configuration file directly in the BROWSERSLIST_CONFIG environment variable.

Shareable Configs

You can import configuration data from another package that prints the Browserslist configuration as follows:

  "browserslist": [
    "extends browserslist-config-mycompany"
  ]
Copy the code

For security purposes, additional configuration packages only support package names with the prefix browserslist-config-. The NPM package scope also supports @scope/browserslist-config, for example: @scope/browserslist-config or @scope/browserslist-config-mycompany.

When writing a shared Browserslist package, just export an array. browserslist-config-mycompany/index.js:

module.exports = [
  'last 1 version'.'> 1%'.'ie 10'
]
Copy the code

Differentiated environment configuration

You can configure different browser queries for different environments. Browserslist will rely on BROWSERSLIST_ENV or NODE_ENV to query the browser version range. If neither environment variable is configured with the correct query condition, then the query condition is loaded from the production configuration item first. If not, the default configuration is applied.

In package.json:

  "browserslist": {
    "production": [
      "1%" >."ie 10"]."development": [
      "last 1 chrome version"."last 1 firefox version"]}Copy the code

In .browserslistrc config:

[production staging]
> 1%
ie 10

[development]
last 1 chrome version
last 1 firefox version
Copy the code

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
Copy the code

Of course, you can generate usage statistics file by any other method. File format should be like:

{
  "ie": {
    "6": 0.01."Seven": 0.4."8": 1.5
  },
  "chrome": {... },... }Copy the code

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.

JS API

var browserslist = require('browserslist');

// Your CSS/JS build tool code
var process = function (source, opts) {
    var browsers = browserslist(opts.browsers, {
        stats: opts.stats,
        path:  opts.file,
        env:   opts.env
    });
    // Your code to add features for selected browsers
}
Copy the code

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.

For non-JS environment and debug purpose you can use CLI tool:

browserslist "> 1%, IE 10"
Copy the code

Coverage

You can get total users coverage for selected browsers by JS API:

browserslist.coverage(browserslist('> 1%'))
/ / = > 81.4
Copy the code
browserslist.coverage(browserslist('> 1% in US'), 'US')
/ / = > 83.1
Copy the code
browserslist.coverage(browserslist('> 1% in my stats'), 'my stats')
/ / = > 83.1
Copy the code
browserslist.coverage(browserslist('> 1% in my stats', { stats }), stats)
/ / = > 82.2
Copy the code

Or by CLI:

$ browserslist --coverage "1%" >
These browsers account for 81.4% of all users globally
Copy the code
$ browserslist --coverage=US "> 1% in US"
These browsers account for 83.1% of all users in the US
Copy the code
$ browserslist --coverage "> 1% in my stats"
These browsers account for 83.1% of all users in custom statistics
Copy the code
$ browserslist --coverage "> 1% in my stats" --stats=./stats.json
These browsers account for 83.1% of all users in custom statistics
Copy the code

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:

browserslist.clearCaches();
Copy the code

To disable the caching altogether, set the BROWSERSLIST_DISABLE_CACHE environment variable.