CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-browserslist

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/browserslist@3.2.x
Publish Source
CLI
Badge
tessl/npm-browserslist badge