Browser Selection

Core functionality for selecting browsers based on queries. The main browserslist function resolves human-readable queries into specific browser versions using Can I Use database data.

Capabilities

Main Function

The primary browserslist function that accepts queries and returns browser lists.

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

interface BrowserslistOptions {
  /** Path to processed file, used to find config files (default: ".") */
  path?: string;
  /** Processing environment for config selection (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;
}

Usage Examples:

const browserslist = require("browserslist");

// Use default queries
const defaultBrowsers = browserslist();
// => ['chrome 88', 'firefox 85', 'safari 14', 'edge 88', ...]

// Single query string
const browsers = browserslist('last 2 versions');
// => ['chrome 88', 'chrome 87', 'firefox 85', 'firefox 84', ...]

// Multiple queries as string
const browsers2 = browserslist('last 2 versions, > 1%, not dead');

// Multiple queries as array
const browsers3 = browserslist(['last 2 versions', '> 1%', 'not dead']);

// With options
const browsers4 = browserslist('> 1%', {
  path: '/path/to/project',
  env: 'development'
});

Query Syntax Support

Browserslist supports a wide range of query patterns:

Version-based queries:

• last 2 versions - Last 2 versions of all browsers
• last 2 Chrome versions - Last 2 versions of specific browser
• last 2 major versions - Last 2 major versions of all browsers
• chrome >= 88 - Chrome version 88 and above
• firefox 85-90 - Firefox versions 85 through 90

Usage-based queries:

• > 1% - Browsers with more than 1% global usage
• >= 0.5% - Browsers with 0.5% or more global usage
• > 1% in US - More than 1% usage in specific country
• > 1% in my stats - More than 1% in custom statistics

Date-based queries:

• last 2 years - Browsers released in last 2 years
• since 2015 - Browsers released since 2015
• since 2015-03 - Browsers released since March 2015
• since 2015-03-10 - Browsers released since specific date

Special queries:

• defaults - Default browserslist queries
• dead - Browsers without official support or updates
• not dead - Exclude dead browsers
• Firefox ESR - Firefox Extended Support Release
• electron >= 1.0 - Electron versions (maps to Chrome)

Coverage queries:

• cover 99.5% - Browsers that cover 99.5% of global usage
• cover 95% in US - Browsers covering 95% in specific country

Negation:

• not ie <= 10 - Exclude Internet Explorer 10 and below
• not dead - Exclude browsers without support

Configuration extending:

• extends @company/browserslist-config - Extend from shared config

Environment Variables

Browserslist behavior can be controlled via environment variables:

• BROWSERSLIST - Override queries directly
• BROWSERSLIST_CONFIG - Override config file path
• BROWSERSLIST_ENV - Override environment name
• BROWSERSLIST_STATS - Override stats file path
• BROWSERSLIST_DISABLE_CACHE - Disable caching
• NODE_ENV - Used as fallback environment name

Static Properties

/** Default queries used when no queries specified */
browserslist.defaults: string[];
// Value: ['> 0.5%', 'last 2 versions', 'Firefox ESR', 'not dead']

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

/** Browser name aliases for compatibility */
browserslist.aliases: object;
// Examples: { fx: 'firefox', ff: 'firefox', ios: 'ios_saf', explorer: 'ie' }

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

Browser vs Node.js Environment

Browserslist provides different behavior in browser vs Node.js environments:

Node.js environment:

• Full configuration file support
• File system access for config discovery
• Custom stats file loading
• Country-specific usage data

Browser environment:

• Limited to basic query resolution
• No file system access
• Custom stats only via options.stats
• No country-specific data loading

Error Handling

The browserslist function throws BrowserslistError for:

// Unknown browser names
browserslist('unknownbrowser 1'); // throws BrowserslistError

// Invalid query syntax
browserslist('invalid query syntax'); // throws BrowserslistError

// Unknown versions (unless ignoreUnknownVersions: true)
browserslist('chrome 999'); // throws BrowserslistError

// Invalid configuration
browserslist(null, { config: 'nonexistent.json' }); // throws BrowserslistError