Skip to content
Get packs

Guide · Open source

How to use Browserslist: config, queries and tools

Updated · written with AI from the project's own documentation and checked against our catalogue data

Browserslist is a shared config format and tool for declaring which browsers and Node.js versions a front-end project targets. Tools such as Autoprefixer, Babel and Stylelint read this one setting, so you do not configure each one separately. This guide shows you where to put the config, how queries work and how to check the result.

Browserslistbrowserslist/browserslist · ★ 13.6k · MIT

Quick start

  1. 1Confirm you have a build tool. Browserslist needs a tool such as Autoprefixer, Babel or Stylelint to read the config. Check that one is already in your project.
  2. 2Add a browserslist entry. Add a browserslist key to package.json, or create a .browserslistrc file. Use the defaults query as a starting point.
  3. 3Refine with queries. Use queries such as last 2 versions or > 0.5% to set your target list, combining them with or, and or commas.
  4. 4Check the result. Run npx browserslist in your project directory to see which browsers are targeted.
  5. 5Keep data current. Run update-browserslist-db to refresh the browser data used by queries.

What Browserslist does and when you need it

Browserslist is a config to share target browsers and Node.js versions between front-end tools. The README lists Autoprefixer, Babel, postcss-preset-env, eslint-plugin-compat, stylelint-no-unsupported-browser-features, postcss-normalize and obsolete-webpack-plugin as tools that use it.

It only has an effect when a build tool reads it. If your project has no CSS or JavaScript toolchain, the config does nothing.

Add a browserslist config to your project

Tools find target browsers automatically once you add a browserslist entry to package.json. You can also use a separate .browserslistrc file. Both examples below come from the README.

  • Put a browserslist key in package.json, or create a .browserslistrc file in your project.
  • Use the defaults query if you want a reasonable setup for most users.
"browserslist": [ "defaults and fully supports es6-module", "maintained node versions" ]

Write queries that stay up to date

Developers set version lists with queries like last 2 versions so they do not need to update versions by hand. Browserslist resolves these queries using caniuse-lite and Can I Use data.

Queries can be combined. An or combiner can be written as the keyword or or as a comma, and an and combiner takes the intersection of queries. The README gives the example last 1 version or > 1%, which is equal to last 1 version, > 1%.

Browserslist can only be started with a query, not with a not combiner, because there is no left-hand query to combine it with.

  • last 1 version or > 1% is the same as last 1 version, > 1%.
  • last 1 version or chrome > 75 and > 1% selects the browser last version or Chrome since 76, intersected with more than 1% marketshare.

Check and update your browser list

Run npx browserslist in your project directory to see the target browsers. The README says this CLI is built in and available in any project with Autoprefixer.

To refresh the underlying browser data, the README points to update-browserslist-db. Browserslist also lists browserslist-lint, which checks your config for common mistakes.

  • Use npx browserslist to see the resolved target list.
  • Use update-browserslist-db to update the caniuse-lite data behind queries like last 2 versions or >1%.
  • Use browserslist-lint to catch popular config mistakes.
npx browserslist

Follow the recommended defaults

The README recommends the defaults query for most users. If you want to change the default set, it recommends including last 2 versions, not dead, > 0.2%, but warns that this should be used with caution.

The README also advises against selecting browsers directly, such as last 2 Chrome versions, unless you build a web app for a kiosk with one browser. Do not remove browsers just because you do not know them.

  • Use the defaults query for a general starting point.
  • Select single browsers only for single-browser environments like a kiosk.
"browserslist": [ "defaults" ]

What people use it for

  • Setting one browser list that Autoprefixer uses to add vendor prefixes to CSS.
  • Sharing the same target list between Babel and Stylelint in one project.
  • Using the playground at browsersl.ist to test how a config resolves before committing it.
  • Generating a user-agent check with browserslist-useragent-regexp to show an unsupported-browser banner.

Frequently asked questions

How do I install Browserslist?

The README describes Browserslist as a package-manager install that needs Node.js. The README's install command is a git clone of the repository, but most projects add it through their package manager and use the config in package.json or .browserslistrc.

Is Browserslist free?

Browserslist is open source under the MIT licence, according to the project page. The README also says the project accepts donations at Open Collective.

Where does Browserslist read its config from?

It checks a .browserslistrc file, a browserslist key in package.json, a browserslist config file, and the BROWSERSLIST environment variable, in that order, in the current or parent directories. If none gives a valid result, it uses its defaults.

What are the default browsers?

If no config is found, the README says Browserslist uses the query > 0.5%, last 2 versions, Firefox ESR, not dead.

Why isn't my Browserslist config doing anything?

The config only has an effect when a tool such as Autoprefixer, Babel or Stylelint reads it. Check that one of those tools is installed and run npx browserslist to see what is resolved.

How does Browserslist compare to Autoprefixer, Babel preset-env or postcss-preset-env?

Autoprefixer, Babel preset-env and postcss-preset-env are tools that consume browser targets, and Browserslist is the shared config they read. The README lists them as users of Browserslist rather than alternatives to it.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Browserslist suits front-end developers who use Autoprefixer, Babel or Stylelint and want one shared browser list that updates as usage data changes. It is not useful for projects with no build tools, or for teams that already set targets in each tool and see no need for a shared list.

Install options & downloads