Browserslist

<img width="120" height="120" alt="Browserslist logo by Anton Popov" src="https://browsersl.ist/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:

  "browserslist": [
    "defaults and fully supports es6-module",
    "maintained node versions"
  ]

Or in .browserslistrc config:

# Browsers that we support

defaults and fully supports es6-module
maintained node versions

Developers set their version lists using queries like last 2 versions to be free from updating versions manually. Browserslist will use caniuse-lite with Can I Use data for this queries.

You can check how config works at our playground: browsersl.ist

<a href="https://browsersl.ist/"> <img src="/img/screenshot.webp" alt="browsersl.ist website"> </a> <br> <br> <div align="center"> <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>  <a href="https://cube.dev/?ref=eco-browserslist-github"><img src="https://user-images.githubusercontent.com/986756/154330861-d79ab8ec-aacb-4af8-9e17-1b28f1eccb01.svg" alt="Supported by Cube" width="227" height="46"></a> </div>

Table of Contents

• Tools
• Best Practices
• Queries
• Config File
• Shareable Configs
• Configuring for Different Environments
• Custom Usage Data
• JS API
• Environment Variables
• Cache
• Security Contact
• For Enterprise

Sponsors

Browserslist needs your support. We are accepting donations at Open Collective.

<a href="https://workleap.com/"><img src="https://github.com/user-attachments/assets/f4f764d3-39ce-4d4e-bdcb-2583ce349812" alt="Sponsored by Workleap" width="154" height="40"></a>      <a href="https://kinsta.com/"><img src="https://github.com/user-attachments/assets/27cd0c29-637a-4c94-a60c-85c056cbac28" alt="Sponsored by Kinsta" width="158" height="40"></a>

Tools

Analyze your Browserslist Config

• 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-lint checks your config for popular mistakes.

Update caniuse-lite

• update-browserslist-db is a CLI tool to update browsers DB for queries like last 2 version or >1%.
• browserslist-update-action is a GitHub Action to automatically run update-browserslist-db and proposes a pull request to merge updates.

Get Statistics for >5% in my stats:

• browserslist-plausible downloads your website browsers statistics from Plausible to use it in > 0.5% in my stats query.
• browserslist-ga and browserslist-ga-export download website browsers statistics from Google Analytics.
• browserslist-new-relic generates a custom usage data file for Browserslist

Show “We do not support your browser” Banner

• browserslist-useragent-regexp compiles Browserslist query to a RegExp to test browser useragent.
• browserslist-useragent-ruby is a Ruby library to check browser by user agent string to match Browserslist.

Others

• browserslist-rs is a Browserslist port to Rust.

Text Editors

These extensions will add syntax highlighting for .browserslistrc files.

• VS Code
• Vim
• WebStorm

Best Practices

• There is a defaults query, which gives a reasonable configuration for most users:

    "browserslist": [
      "defaults"
    ]
  

• If you want to change the default set of browsers, we recommend including last 2 versions, not dead, > 0.2%. This is because last n versions on its own does not add popular old versions, while only using a percentage of usage numbers 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.

• 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.

• 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. .browserslistrc config file in current or parent directories.
2. browserslist key in package.json 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 all the previous queries: last 1 version or chrome > 75 and > 1% will select (browser last version or Chrome since 76) and more than 1% marketshare.

There are 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. The left-hand is always resolved as and combiner even if or is used (this is an API implementation specificity).

| 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) | | These three are equivalent to one another: <br> > .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.3%, not dead' in your terminal.

Full List

You can specify the browser and Node.js versions by queries (case insensitive):

• defaults: Browserslist’s default browsers (> 0.5%, last 2 versions, Firefox ESR, not dead).
• By usage statistics:
  • > 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].
  • > 5% in browserslist-config-mycompany stats: uses [custom usage data] from browserslist-config-mycompany/browserslist-stats.json.
  • cover 99.5%: most popular browsers that provide cove