↓Skip to main content
Dev Blog Dev Blog
  1. All Posts/

browserslist

Tools JavaScript

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 supports es6-module",
    "maintained node versions"
  ]

Or in .browserslistrc config:

# Browsers that we support

defaults and 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


<p>
  </a>
</p>

<h2 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-table-of-contents" class="anchor" aria-hidden="true" href="#table-of-contents"></a>Table of Contents
</h2>

<ul dir="auto">
  <li>
    <a rel="nofollow noopener" target="_blank" href="#tools">Tools</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#best-practices">Best Practices</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#queries">Queries</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#config-file">Config File</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#shareable-configs">Shareable Configs</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#configuring-for-different-environments">Configuring for Different Environments</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#custom-usage-data">Custom Usage Data</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#js-api">JS API</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#environment-variables">Environment Variables</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#cache">Cache</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#security-contact">Security Contact</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#for-enterprise">For Enterprise</a>
  </li>
</ul>

<h2 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-tools" class="anchor" aria-hidden="true" href="#tools"></a>Tools
</h2>

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-analyze-your-browserslist-config" class="anchor" aria-hidden="true" href="#analyze-your-browserslist-config"></a>Analyze your Browserslist Config
</h3>

<ul dir="auto">
  <li>
    Run <code>npx browserslist</code> in your project directory to see project’s<br /> target browsers. This CLI tool is built-in and available in any project<br /> with Autoprefixer.
  </li>
  <li>
    <code>browserslist-lint</code> checks your config for popular mistakes.
  </li>
</ul>

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-update-caniuse-lite" class="anchor" aria-hidden="true" href="#update-caniuse-lite"></a>Update <code>caniuse-lite</code><br />
</h3>

<ul dir="auto">
  <li>
    <code>update-browserslist-db</code> is a CLI tool to update browsers DB for queries<br /> like <code>last 2 version</code> or <code>&gt;1%</code>.
  </li>
  <li>
    <code>browserslist-update-action</code> is a GitHub Action to automatically<br /> runs <code>update-browserslist-db</code> and proposes a pull request to merge updates.
  </li>
</ul>

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-show-we-do-not-support-your-browser-banner" class="anchor" aria-hidden="true" href="#show-we-do-not-support-your-browser-banner"></a>Show “We do not support your browser” Banner
</h3>

<ul dir="auto">
  <li>
    <code>browserslist-useragent-regexp</code> compiles Browserslist query to a RegExp<br /> to test browser useragent.
  </li>
  <li>
    <code>browserslist-useragent-ruby</code> is a Ruby library to checks browser<br /> by user agent string to match Browserslist.
  </li>
</ul>

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-get-statistics-for-5-in-my-stats" class="anchor" aria-hidden="true" href="#get-statistics-for-5-in-my-stats"></a>Get Statistics for <code>&gt;5% in my stats</code>:
</h3>

<ul dir="auto">
  <li>
    <code>browserslist-ga</code> and <code>browserslist-ga-export</code> download your website<br /> browsers statistics to use it in <code>&gt; 0.5% in my stats</code> query.
  </li>
  <li>
    <code>browserslist-new-relic</code> generate a custom usage data file for Browserslist
  </li>
  <li>
    <code>browserslist-adobe-analytics</code> use Adobe Analytics data to target browsers.<br /> from your New Relic Browser data.
  </li>
</ul>

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-others" class="anchor" aria-hidden="true" href="#others"></a>Others
</h3>

<ul dir="auto">
  <li>
    <code>browserslist-rs</code> is a Browserslist port to Rust.
  </li>
  <li>
    <code>browserslist-browserstack</code> runs BrowserStack tests for all browsers<br /> in Browserslist config.
  </li>
</ul>

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-text-editors" class="anchor" aria-hidden="true" href="#text-editors"></a>Text Editors
</h3>

<p>
  These extensions will add syntax highlighting for <code>.browserslistrc</code> files.
</p>

<ul dir="auto">
  <li>
    <a rel="nofollow noopener" target="_blank" href="https://marketplace.visualstudio.com/items?itemName=webben.browserslist">VS Code</a>
  </li>
  <li>
    Vim
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="https://plugins.jetbrains.com/plugin/16139-browserslist">WebStorm</a>
  </li>
</ul>

<h2 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-best-practices" class="anchor" aria-hidden="true" href="#best-practices"></a>Best Practices
</h2>

<ul dir="auto">
  <li>
    There is a <code>defaults</code> query, which gives a reasonable configuration<br /> for most users:</p> <pre>  "browserslist": [
"defaults"

] 

  <li>
    If you want to change the default set of browsers, we recommend including<br /> <code>last 2 versions, not dead, &gt; 0.2%</code>. This is because <code>last n versions</code> on its<br /> own does not add popular old versions, while only using a percentage of usage<br /> numbers above <code>0.2%</code> will in the long run make popular browsers even more<br /> popular. We might run into a monopoly and stagnation situation, as we had with<br /> Internet Explorer 6. Please use this setting with caution.
  </li>
  <li>
    Select browsers directly (<code>last 2 Chrome versions</code>) only if you are making<br /> a web app for a kiosk with one browser. There are a lot of browsers<br /> on the market. If you are making general web app you should respect<br /> browsers diversity.
  </li>
  <li>
    Don’t remove browsers just because you don’t know them. Opera Mini has<br /> 100 million users in Africa and it is more popular in the global market<br /> than Microsoft Edge. Chinese QQ Browsers has more market share than Firefox<br /> and desktop Safari combined.
  </li>
</ul>

<h2 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-queries" class="anchor" aria-hidden="true" href="#queries"></a>Queries
</h2>

<p>
  Browserslist will use browsers and Node.js versions query<br /> from one of these sources:
</p>

<ol dir="auto">
  <li>
    <code>.browserslistrc</code> config file in current or parent directories.
  </li>
  <li>
    <code>browserslist</code> key in <code>package.json</code> file in current or parent directories.
  </li>
  <li>
    <code>browserslist</code> config file in current or parent directories.
  </li>
  <li>
    <code>BROWSERSLIST</code> environment variable.
  </li>
  <li>
    If the above methods did not produce a valid result<br /> Browserslist will use defaults:<br /> <code>&gt; 0.5%, last 2 versions, Firefox ESR, not dead</code>.
  </li>
</ol>

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-query-composition" class="anchor" aria-hidden="true" href="#query-composition"></a>Query Composition
</h3>

<p>
  An <code>or</code> combiner can use the keyword <code>or</code> as well as <code>,</code>.<br /> <code>last 1 version or &gt; 1%</code> is equal to <code>last 1 version, &gt; 1%</code>.<br /> <code>and</code> query combinations are also supported to perform an<br /> intersection of all the previous queries:<br /> <code>last 1 version or chrome &gt; 75 and &gt; 1%</code> will select<br /> (<code>browser last version</code> or <code>Chrome since 76</code>) and <code>more than 1% marketshare</code>.<br /> There are 3 different ways to combine queries as depicted below. First you start<br /> with a single query and then we combine the queries to get our final list.<br /> Obviously you can not start with a <code>not</code> combiner, since there is no left-hand<br /> side query to combine it with. The left-hand is always resolved as <code>and</code><br /> combiner even if <code>or</code> is used (this is an API implementation specificity).
</p>

<p>
  Query combiner type<br /> Illustration<br /> Example
</p>

<p>
  <code>or</code>/<code>,</code> combiner (union)
</p>

<p>
  <code>&gt; .5% or last 2 versions</code> <code>&gt; .5%, last 2 versions</code>
</p>

<p>
  <code>and</code> combiner (intersection)
</p>

<p>
  <code>&gt; .5% and last 2 versions</code>
</p>

<p>
  <code>not</code> combiner (relative complement)
</p>

<p>
  These three are equivalent to one another: <code>&gt; .5% and not last 2 versions</code> <code>&gt; .5% or not last 2 versions</code> <code>&gt; .5%, not last 2 versions</code>
</p>

<p>
  A quick way to test your query is to do <code>npx browserslist '&gt; 0.3%, not dead'</code><br /> in your terminal.
</p>

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-full-list" class="anchor" aria-hidden="true" href="#full-list"></a>Full List
</h3>

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

<ul dir="auto">
  <li>
    <code>defaults</code>: Browserslist’s default browsers<br /> (<code>&gt; 0.5%, last 2 versions, Firefox ESR, not dead</code>).
  </li>
  <li>
    By usage statistics: <ul dir="auto">
      <li>
        <code>&gt; 5%</code>: browsers versions selected by global usage statistics.<br /> <code>&gt;=</code>, <code>&lt;</code> and <code>&lt;=</code> work too.
      </li>
      <li>
        <code>&gt; 5% in US</code>: uses USA usage statistics.<br /> It accepts <a rel="nofollow noopener" target="_blank" href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements">two-letter country code</a>.
      </li>
      <li>
        <code>&gt; 5% in alt-AS</code>: uses Asia region usage statistics.<br /> List of all region codes can be found at <code>caniuse-lite/data/regions</code>.
      </li>
      <li>
        <code>&gt; 5% in my stats</code>: uses <a rel="nofollow noopener" target="_blank" href="#custom-usage-data">custom usage data</a>.
      </li>
      <li>
        <code>&gt; 5% in browserslist-config-mycompany stats</code>: uses <a rel="nofollow noopener" target="_blank" href="#custom-usage-data">custom usage data</a><br /> from <code>browserslist-config-mycompany/browserslist-stats.json</code>.
      </li>
      <li>
        <code>cover 99.5%</code>: most popular browsers that provide coverage.
      </li>
      <li>
        <code>cover 99.5% in US</code>: same as above, with <a rel="nofollow noopener" target="_blank" href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements">two-letter country code</a>.
      </li>
      <li>
        <code>cover 99.5% in my stats</code>: uses <a rel="nofollow noopener" target="_blank" href="#custom-usage-data">custom usage data</a>.
      </li>
    </ul>
  </li>
  
  <li>
    Last versions: <ul dir="auto">
      <li>
        <code>last 2 versions</code>: the last 2 versions for each browser.
      </li>
      <li>
        <code>last 2 Chrome versions</code>: the last 2 versions of Chrome browser.
      </li>
      <li>
        <code>last 2 major versions</code> or <code>last 2 iOS major versions</code>:<br /> all minor/patch releases of last 2 major versions.
      </li>
    </ul>
  </li>
  
  <li>
    <code>dead</code>: browsers without official support or updates for 24 months.<br /> Right now it is <code>IE 11</code>, <code>IE_Mob 11</code>, <code>BlackBerry 10</code>, <code>BlackBerry 7</code>,<br /> <code>Samsung 4</code>, <code>OperaMobile 12.1</code> and all versions of <code>Baidu</code>.
  </li>
  <li>
    Node.js versions: <ul dir="auto">
      <li>
        <code>node 10</code> and <code>node 10.4</code>: selects latest Node.js <code>10.x.x</code><br /> or <code>10.4.x</code> release.
      </li>
      <li>
        <code>last 2 node versions</code>: select 2 latest Node.js releases.
      </li>
      <li>
        <code>last 2 node major versions</code>: select 2 latest major-version Node.js releases.
      </li>
      <li>
        <code>current node</code>: Node.js version used by Browserslist right now.
      </li>
      <li>
        <code>maintained node versions</code>: all Node.js versions, which are still maintained<br /> by Node.js Foundation.
      </li>
    </ul>
  </li>
  
  <li>
    Browsers versions: <ul dir="auto">
      <li>
        <code>iOS 7</code>: the iOS browser version 7 directly.
      </li>
      <li>
        <code>Firefox &gt; 20</code>: versions of Firefox newer than 20.<br /> <code>&gt;=</code>, <code>&lt;</code> and <code>&lt;=</code> work too. It also works with Node.js.
      </li>
      <li>
        <code>ie 6-8</code>: selects an inclusive range of versions.
      </li>
      <li>
        <code>Firefox ESR</code>: the latest <a rel="nofollow noopener" target="_blank" href="https://support.mozilla.org/en-US/kb/choosing-firefox-update-channel">Firefox Extended Support Release</a>.
      </li>
      <li>
        <code>PhantomJS 2.1</code> and <code>PhantomJS 1.9</code>: selects Safari versions similar<br /> to PhantomJS runtime.
      </li>
    </ul>
  </li>
  
  <li>
    <code>extends browserslist-config-mycompany</code>: take queries from<br /> <code>browserslist-config-mycompany</code> npm package.
  </li>
  <li>
    <code>supports es6-module</code>: browsers with support for specific features.<br /> <code>es6-module</code> here is the <code>feat</code> parameter at the URL of the <a rel="nofollow noopener" target="_blank" href="https://caniuse.com/">Can I Use</a><br /> page. A list of all available features can be found at<br /> <code>caniuse-lite/data/features</code>.
  </li>
  <li>
    <code>browserslist config</code>: the browsers defined in Browserslist config. Useful<br /> in Differential Serving to modify user’s config like<br /> <code>browserslist config and supports es6-module</code>.
  </li>
  <li>
    <code>since 2015</code> or <code>last 2 years</code>: all versions released since year 2015<br /> (also <code>since 2015-03</code> and <code>since 2015-03-10</code>).
  </li>
  <li>
    <code>unreleased versions</code> or <code>unreleased Chrome versions</code>:<br /> alpha and beta versions.
  </li>
  <li>
    <code>not ie &lt;= 8</code>: exclude IE 8 and lower from previous queries.
  </li>
</ul>

<p>
  You can add <code>not </code> to any query.
</p>

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-grammar-definition" class="anchor" aria-hidden="true" href="#grammar-definition"></a>Grammar Definition
</h3>

<p>
  There is a grammar specification about the query syntax,<br /> which may be helpful if you&#8217;re implementing a parser or something else.
</p>

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-debug" class="anchor" aria-hidden="true" href="#debug"></a>Debug
</h3>

<p>
  Run <code>npx browserslist</code> in a project directory to see which browsers were selected<br /> by your queries.
</p>

<pre>$ 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 5

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-browsers" class="anchor" aria-hidden="true" href="#browsers"></a>Browsers
</h3>

<p>
  The following table maps browser names & their target devices into identifiers used by browserslist.
</p>

<p>
  Browser Name<br /> Desktop<br /> Android<br /> iOS<br /> Other Mobile
</p>

<p>
  Android (WebView)
</p>

<p>
  <code>Android</code>
</p>

<p>
  Baidu<br /> <code>Baidu</code>
</p>

<p>
  BlackBerry
</p>

<p>
  <code>BlackBerry</code> <code>bb</code>
</p>

<p>
  Chrome<br /> <code>Chrome</code>
</p>

<p>
  <code>ChromeAndroid</code> <code>and_chr</code>
</p>

<p>
  ↪︎ <code>ios_saf</code>2
</p>

<p>
  Edge<br /> <code>Edge</code><br /> ↪︎ <code>and_chr</code>
</p>

<p>
  ↪︎ <code>ios_saf</code>2
</p>

<p>
  Electron<br /> <code>Electron</code>
</p>

<p>
  Firefox
</p>

<p>
  <code>Firefox</code> <code>ff</code>
</p>

<p>
  <code>FirefoxAndroid</code> <code>and_ff</code>
</p>

<p>
  ↪︎ <code>ios_saf</code>2
</p>

<p>
  Internet Explorer
</p>

<p>
  <code>Explorer</code> <code>ie</code>
</p>

<p>
  <code>ie_mob</code>
</p>

<p>
  Node.js<br /> <code>Node</code>
</p>

<p>
  <a rel="nofollow noopener" target="_blank" href="https://medium.com/design-at-kai/what-you-didnt-know-about-kaios-browser-53937ea1636">KaiOS Browser</a>
</p>

<p>
  <code>kaios</code>
</p>

<p>
  Opera<br /> <code>Opera</code>
</p>

<p>
  <code>op_mob</code> 1
</p>

<p>
  ↪︎ <code>ios_saf</code>2
</p>

<p>
  <a rel="nofollow noopener" target="_blank" href="https://en.wikipedia.org/wiki/Opera_Mini">Opera Mini</a>
</p>

<p>
  <code>OperaMini</code>
</p>

<p>
  <a rel="nofollow noopener" target="_blank" href="https://en.wikipedia.org/wiki/QQ_browser">QQ browser</a>
</p>

<p>
  <code>and_qq</code>
</p>

<p>
  Safari<br /> <code>Safari</code>
</p>

<p>
  <code>iOS</code> <code>ios_saf</code>
</p>

<p>
  Samsung Internet
</p>

<p>
  <code>Samsung</code>
</p>

<p>
  <a rel="nofollow noopener" target="_blank" href="https://en.wikipedia.org/wiki/UC_Browser">UC Browser</a>
</p>

<p>
  <code>UCAndroid</code> <code>and_uc</code>
</p>

<ul dir="auto">
  <li>
    <code>↪︎ name</code> implies that the browser uses the same engine captured by <code>name</code>
  </li>
  <li>
    1 Opera Mobile ≈ Chrome Android
  </li>
  <li>
    2 <a rel="nofollow noopener" target="_blank" href="https://en.wikipedia.org/wiki/WebKit">All iOS browsers use WebKit</a>
  </li>
</ul>

<h2 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-config-file" class="anchor" aria-hidden="true" href="#config-file"></a>Config File
</h2>

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-packagejson" class="anchor" aria-hidden="true" href="#packagejson"></a><code>package.json</code><br />
</h3>

<p>
  If you want to reduce config files in project root, you can specify<br /> browsers in <code>package.json</code> with <code>browserslist</code> key:
</p>

<pre>{

“private”: true, “dependencies”: { “autoprefixer”: “^6.5.4” }, “browserslist”: [ “last 1 version”, “> 1%”, “not dead” ] }

<h3 dir="auto">
  <a rel="nofollow noopener" target="_blank" id="user-content-browserslistrc" class="anchor" aria-hidden="true" href="#browserslistrc"></a><code>.browserslistrc</code><br />
</h3>

<p>
  Separated Browserslist config should be named <code>.browserslistrc</code><br /> and have browsers queries split by a new line.<br /> Each line is combined with the <code>or</code> combiner. Comments starts with <code>#</code> symbol:
</p>

<pre># Browsers that we support

last 1 version > 1% not dead # no browsers without security updates

<p>
  Browserslist will check config in every directory in <code>path</code>.<br /> So, if tool process <code>app/styles/main.css</code>, you can put config to root,<br /> <code>app/</code> or <code>app/styles</code>.<br /> You can specify&#8230;
</p>
↑