or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser-selection.mdconfiguration.mdcoverage-analysis.mdindex.md
tile.json

tessl/npm-browserslist

Share target browsers between different front-end tools, like Autoprefixer, Stylelint and babel-env-preset

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/browserslist@3.2.x

To install, run

npx @tessl/cli install tessl/npm-browserslist@3.2.0

index.mddocs/

Browserslist

Browserslist provides shared browser configuration for different front-end tools like Autoprefixer, Babel, Stylelint, and other build tools. It enables developers to define browser support requirements using human-readable queries (like 'last 2 versions', '> 1%', 'IE 10') that are automatically resolved using Can I Use database data.

Package Information

  • Package Name: browserslist
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install browserslist

Core Imports

const browserslist = require("browserslist");

For ES modules:

import browserslist from "browserslist";

Basic Usage

const browserslist = require("browserslist");

// Get browsers for default queries
const browsers = browserslist();
console.log(browsers);
// => ['chrome 88', 'firefox 85', 'safari 14', ...]

// Use specific queries
const modernBrowsers = browserslist('last 2 versions, > 1%');
console.log(modernBrowsers);

// Calculate market coverage
const coverage = browserslist.coverage(modernBrowsers);
console.log(`Coverage: ${coverage}%`);

Architecture

Browserslist is built around several key components:

  • Query Engine: Parses and resolves human-readable browser queries into specific browser versions
  • Data Integration: Uses Can I Use database and Electron-to-Chromium mappings for up-to-date browser information
  • Configuration System: Supports multiple configuration methods including package.json, config files, and environment variables
  • Environment Support: Works in both Node.js and browser environments with appropriate fallbacks
  • Usage Statistics: Integrates global and custom browser usage data for percentage-based queries

Capabilities

Browser Selection

Core functionality for selecting browsers based on queries. Returns browser lists in Can I Use format for use with build tools.

/**
 * Return array of browsers by selection queries
 * @param queries - Browser queries (defaults to browserslist.defaults)
 * @param opts - Options object
 * @returns Array with browser names in Can I Use format
 */
function browserslist(
  queries?: string | string[],
  opts?: BrowserslistOptions
): string[];

interface BrowserslistOptions {
  /** Path to processed file (default: current directory) */
  path?: string;
  /** Processing environment (default: "production") */
  env?: string;
  /** Path to config file with queries */
  config?: string;
  /** Custom browser usage statistics for "> 1% in my stats" query */
  stats?: string | object;
  /** Do not throw on unknown version in direct query (default: false) */
  ignoreUnknownVersions?: boolean;
  /** Disable security checks for extend query (default: false) */
  dangerousExtend?: boolean;
}

Browser Selection

Market Coverage Analysis

Calculate market coverage percentage for browser lists. Essential for understanding the reach of browser support decisions.

/**
 * Return browsers market coverage
 * @param browsers - Browser names in Can I Use format
 * @param stats - Statistics to use ("global", "my stats", country codes, or custom object)
 * @returns Total market coverage percentage
 */
browserslist.coverage(
  browsers: string[],
  stats?: string | object
): number;

Coverage Analysis

Configuration Management

Configuration loading and parsing for different file formats and environments. Supports package.json, .browserslistrc, and browserslist config files.

/**
 * Load configuration with environment resolution
 * @param opts - Options object with path, env, config properties
 * @returns Loaded configuration queries
 */
browserslist.loadConfig(opts: ConfigLoadOptions): string[] | object | undefined;

/**
 * Find browserslist configuration in directory tree
 * @param from - Starting directory path
 * @returns Found configuration or undefined
 */
browserslist.findConfig(from: string): object | undefined;

/**
 * Parse browserslist configuration string
 * @param string - Configuration string to parse
 * @returns Parsed configuration with environment sections
 */
browserslist.parseConfig(string: string): object;

/**
 * Read and parse configuration file
 * @param file - Path to configuration file
 * @returns Parsed configuration
 */
browserslist.readConfig(file: string): object;

interface ConfigLoadOptions {
  /** Starting directory path */
  path?: string;
  /** Environment name */
  env?: string;
  /** Path to specific config file */
  config?: string;
}

Configuration Management

Static Properties

/** Default browser queries used when no queries specified */
browserslist.defaults: string[];

/** Browser data from Can I Use database */
browserslist.data: object;

/** Browser usage statistics (global and custom) */
browserslist.usage: {
  global: object;
  custom: object | null;
};

/** Browser name aliases (fx -> firefox, etc.) */
browserslist.aliases: object;

/** Version aliases for browsers with joined versions */
browserslist.versionAliases: object;

Command Line Interface

Browserslist provides a command-line tool for querying browsers and calculating coverage.

# Install globally or use via npx
npm install -g browserslist
# or
npx browserslist

# Basic usage
browserslist                    # Use default queries
browserslist "last 2 versions" # Use specific queries
browserslist --coverage "last 2 versions"  # Show coverage percentage

# Configuration options
browserslist --config="path/to/config"     # Use specific config file
browserslist --env="development"           # Use specific environment
browserslist --stats="path/to/stats.json"  # Use custom statistics
browserslist --coverage=US "last 2 versions" # Coverage for specific country

The CLI supports all the same queries as the JavaScript API and can be used for debugging browser configurations in build processes.

Error Handling

/**
 * Custom error class for browserslist-specific errors
 */
class BrowserslistError extends Error {
  name: "BrowserslistError";
  message: string;
  browserslist: true;
}

Browserslist throws BrowserslistError for:

  • Unknown browser names
  • Invalid version numbers
  • Malformed configuration files
  • Missing configuration when expected
  • Invalid query syntax