Use Baseline with Browserslist

Tony Conway

Published: May 7, 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, 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:

• Autoprefixer
• Babel using @babel/preset-env
• PostCSS using postcss-preset-env
• ESLint using eslint-plugin-compat
• Stylelint using stylelint-no-unsupported-browser-features
• webpack

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.

Install browserslist-config-baseline

Once you've decided which Baseline feature set you want to target, you can apply that target to your developer tools. The simplest way to do this for any tools that use browserslist is to install browserslist-config-baseline:

# npm
npm i browserslist-config-baseline@latest -D

# yarn
yarn add --latest browserslist-config-baseline -D

# bun
bun add browserslist-config-baseline@latest -d

How to target Baseline Widely available

To target Baseline Widely available, update or add a browserlist config in package.json using the extends keyword:

{
  ...
  "browserslist": [
    "extends browserslist-config-baseline"
   ]
  ...
}

When browserslist loads its list of supported browsers, browserslist-config-baseline will dynamically generate the current minimum browser versions that support all of the features that are now Widely available. You can also add extends browserslist-config-baseline to a .browserslistrc file and it will be handled in the same way.

How to target Baseline years

If you want to target a Baseline year feature set, add a / and the year in the format YYYY to the end of your browserslist query:

"browserslist": "extends browserslist-config-baseline/2020"

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.

browserslist-config-baseline uses baseline-browser-mapping to correlate browser versions to the feature sets they support. Mappings for UC Browser mobile and QQ Browser mobile are available in baseline-browser-mapping and other browsers may be included in the future.

To include these browsers in your Baseline configuration, add /with-downstream immediately after the module name in your browserslist configuration:

"browserslist": "extends browserslist-config-baseline/with-downstream"

Or:

"browserslist": "extends browserslist-config-baseline/with-downstream/2020"

Examples of browserslist-config-baseline in action

In packaging tools

Adding browserslist-config-baseline to your repository 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:

However, setting browserslist-config-baseline to target Baseline 2020 on the same example project dramatically decreases the output size of this Javascript, because fewer syntax transforms are required:

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 browserslist-config-baseline:

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

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

Stylelint also provides a plugin that lets you set Baseline rules directly, but if you are already using browserslist to handle your config, the browserslist-config-baseline is a drop-in solution.

How to contribute to browserslist-config-baseline

If you'd like to make a feature request for browserslist-config-baseline, create an issue or pull request on the GitHub repository.

If you'd like to contribute more downstream browser data or report a data issue, create an issue or a pull request in the baseline-browser-mapping repository.