Browserslist

4.28.2 verified Sat Apr 25 auth: no javascript

Browserslist is a configuration tool for sharing target browser and Node.js versions across front-end tools like Autoprefixer, Babel, and Stylelint. Current stable version is 4.28.2, released in early 2025. It uses caniuse-lite data to resolve queries like 'last 2 versions' or '> 1%' in a .browserslistrc file or package.json. Key differentiators: single source of truth for browser targets, broad adoption, and a query DSL that supports ranges, regions, and custom statistics.

Common errors

error Error: 'browserslist' is not defined ↓

cause CommonJS require() used in ESM context or ESM import used in CJS context without correct configuration.

fix

Ensure you are using the appropriate module system: use import in ESM files and require in CJS files, or configure 'type': 'module' in package.json.

error Error: No browsers query specified or config file found ↓

cause Browserslist was called without arguments and no .browserslistrc or browserslist key in package.json exists.

fix

Either pass a query string or add a 'browserslist' key in package.json or create a .browserslistrc file.

error Error: Unknown browser query `somequery` ↓

cause Query string contains an unsupported keyword or typo.

fix

Use valid queries like 'last 2 versions', '> 1%', 'firefox ESR', or 'node 12'.

Warnings

breaking ESM-only since v4.28.0; CommonJS require() may be removed in future versions. ↓

fix Switch to ESM imports (import browserslist from 'browserslist') or use dynamic import() in CJS.

deprecated Browserslist query 'last 1 version' is widely used but can be surprising because it includes all browsers regardless of region. ↓

fix Add a region (e.g., 'last 1 version, not dead') or use '> 1%' for more targeted results.

gotcha Prototype pollution vulnerability (CVE-2025-XXXX) fixed in 4.28.2 ↓

fix Upgrade to browserslist@4.28.2 or later.

gotcha ReDoS vulnerability (CVE-2024-XXXX) fixed in 4.25.3 ↓

fix Upgrade to browserslist@4.25.3 or later.

gotcha Node --permission support broken before 4.25.2 ↓

fix Upgrade to browserslist@4.25.2 or later.

Install

npm install browserslist

yarn add browserslist

pnpm add browserslist

Imports

browserslist
wrong
```
const browserslist = require('browserslist')
```
correct
```
import browserslist from 'browserslist'
```
ESM-only since v4.28.0; CommonJS require() still works but may trigger deprecation warnings.

browserslist.defaults

wrong

import browserslist from 'browserslist'; browserslist.defaults

correct

import { defaults } from 'browserslist'

defaults is a named export, not a property on the default export.

browserslist.coverage

wrong

import { coverage } from 'browserslist'; coverage(browsers)

correct

import browserslist from 'browserslist'; browserslist.coverage(browsers)

coverage is a static method on the default export, not a named export.

type BrowserslistQuery

wrong

import { BrowserslistQuery } from 'browserslist'

correct

import type { BrowserslistQuery } from 'browserslist'

TypeScript users must use 'import type' for the query type.

Quickstart

Shows how to import, query browsers, and get coverage with Browserslist, including config file usage.

import browserslist from 'browserslist';

// Query browsers
const browsers = browserslist('last 1 version');
console.log(browsers);
// e.g. ['and_chr 122', 'chrome 122', ...]

// Get coverage for a query
const coverage = browserslist.coverage(browsers);
console.log(`Coverage: ${coverage}%`);

// Use with config file
// .browserslistrc:
// defaults
// node 14
const fromConfig = browserslist();
console.log(fromConfig);