Use Baseline with Browserslist

Published: May 7, 2025, Last updated: September 17, 2025

Browserslist is one of the most popular tools for configuring minimum supported browser versions in frontend code bases. Developers add a browserslist query to their package.json file (or other configuration point for Browserslist, such as a .browserslistrc file), and Browserslist exposes a list of minimum supported browsers. Browserslist can be used with a wide range of popular linting, polyfilling and packaging tools, including:

Baseline targets

When you decide to use Baseline, you should consider your user base and decide which Baseline feature set you want to target:

  • Baseline Widely available includes all web features that were fully supported by the Baseline core browser set 30 or more months in the past.
  • Baseline year feature sets, for example Baseline 2020, include all features that were Newly available at the end of the specified year.

Depending on your user base, you may be able to target Baseline Widely available, or you may need to target an older Baseline year. Consult your analytics or RUM tools to understand which browsers versions your users have.

How to target Baseline Newly or Widely available

Support for Baseline is built into Browserslist through a few different queries. If you want to target Baseline Newly available browsers, try specifying baseline newly available in your Browserslist config:

{
  ...
  "browserslist": [
    "baseline newly available"
   ]
  ...
}

You can specify baseline widely available as a query, too:

{
  ...
  "browserslist": [
    "baseline widely available"
   ]
  ...
}

How to target Baseline years

If you want to target a Baseline year feature set, you specify the year in a query, such as baseline 2024 if you want to target the 2024 feature set:

"browserslist": "baseline 2024"

You can specify years from baseline 2015 to the current year.

How to specify downstream browsers

The Baseline core browser set includes Chrome, Edge, Firefox, and Safari. Other browsers are based on the same open source code as Chrome and Edge—Chromium—and should support the same feature set as whichever version of Chromium they implement. To include these browsers in your Baseline configuration, add with downstream after your Baseline query. For example, to target downstream browsers as part of Baseline Widely available, specify baseline widely available with downstream:

"browserslist": "baseline widely available with downstream"

baseline newly available with downstream is another valid query, as is adding with downstream to yearly targets:

"browserslist": "baseline 2024 with downstream"

Examples of Baseline queries in action

In packaging tools

Using the Baseline queries offered by Browserslist in your project can have an immediate effect. Babel is a popular build tool for packaging Javascript. If you use the @babel/preset-env package defaults, many modern Javascript APIs and methods will be replaced with the more verbose syntax required by older browsers:

A terminal session showing that the npm run build command has been executed on a Javascript file called test.js.  The output file size is 12 kilobytes.

However, using a query of baseline 2020 to target the 2020 feature set on the same example project dramatically decreases the output size of this Javascript, because fewer syntax transforms are required:

A second terminal session showing that the npm run build command has now produced a 1.5 kilobyte file when babel is set to target Baseline 2020.

Try this for yourself using the example code in the Google Chrome Labs baseline-demos repository.

In linters

Some linters already work with Browserslist, or can be made to work with Browserslist using a compatibility module. For example, stylelint can consume a browserslist config using the stylelint-browser-compat module. Set your stylelint.config.js file to use the Baseline query of your choice:

module.exports = {
  plugins: ['stylelint-browser-compat'],
  rules: {
    'plugin/browser-compat': [
      true,
      {
        browserslist: ['baseline widely available'],
      },
    ],
  },
};

Stylelint will now flag CSS that isn't currently part of Baseline Widely available:

a list of warnings from Stylelint highlighting CSS code that doesn't work on older browsers.

Stylelint also provides a plugin that lets you set Baseline rules directly, but if you are already using Browserslist to handle your config, using the built-in Baseline queries that Browserslist offers is a viable solution.