Browserslist

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

  

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.

      

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:

json "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

(union) | | > .5% or last 2 versions

> .5%, last 2 versions | | and combiner

(intersection) | | > .5% and last 2 versions | | not combiner

(relative complement) | | These three are equivalent to one another:

> .5% and not last 2 versions

> .5% or not last 2 versions

> .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 coverage.
• cover 99.5% in US: same as above, with [two-letter country code].
• cover 99.5% in my stats: uses [custom usage data].
• cover 99.5% in browserslist-config-mycompany stats: uses [custom usage data] from browserslist-config-mycompany/browserslist-stats.json.
• By Baseline:
• baseline widely available: browser versions that support all Baseline Widely available features which have been interoperable in the Baseline core browser set for at least 30 months.
• baseline newly available: browser versions that support all Baseline Newly available features which are interoperable in the Baseline core browser set today.
• baseline widely available on YYYY-MM-DD: selects browser versions that supported the Widely available feature set on the specified date.
• baseline 2022: selects browser versions that are compatible with all features that were Baseline Newly available at the end of the specified year.
• … with downstream: includes browsers outside the core browser set that support the requested Baseline feature set based on their Chromium or Gecko version. See baseline-browser-mapping.
• … with downstream including kaios: same output as the previous query plus KaiOS.
• Last versions:
• last 2 versions: the last 2 versions for each browser.
• last 2 Chrome versions: the last 2 versions of Chrome browser.
• last 2 major versions or last 2 iOS major versions: all minor/patch releases of last 2 major versions.
• dead: browsers without official support or updates for 24 months. Right now it is IE 11, IE_Mob 11, BlackBerry 10, BlackBerry 7, Samsung 4, OperaMobile 12.1 and all versions of Baidu.
• Node.js versions:
• node 10 and node 10.4: selects latest Node.js 10.x.x or 10.4.x release.
• last 2 node versions: select 2 latest Node.js releases.
• last 2 node major versions: select 2 latest major-version Node.js releases.
• current node: Node.js version used by Browserslist right now.
• maintained node versions: all Node.js versions, which are [still maintained] by the Node.js team.
• Browsers versions:
• iOS 7: the iOS browser version 7 directly. Note, that op_mini has special version all.
• Firefox > 20: versions of Firefox newer than 20. >=, < and <= work too. It also works with Node.js.
• ie 6-8: selects an inclusive range of versions.
• Firefox ESR: the latest [Firefox Extended Support Release].
• PhantomJS 2.1 and PhantomJS 1.9: selects Safari versions similar to PhantomJS runtime.
• extends browserslist-config-mycompany: take queries from browserslist-config-mycompany npm package.
• By browser support:

In these example queries es6 and es6-module are the the feat parameter from the URL of the Can I Use page. A list of all available features can be found at [caniuse-lite/data/features]. - fully supports es6: browsers with full support for specific features. For example, fully supports css-grid will omit Edge 12-15, as those browser versions are marked as [having partial support]. - partially supports es6-module or supports es6-module: browsers with full or partial support for specific features. For example, partially supports css-grid will include Edge 12-15 support, as those browser versions are marked as [having partial support]. - browserslist config: the br