or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

browser-selection.md configuration.md coverage-analysis.md index.md

tile.json

Coverage Analysis

Calculate market coverage percentage for browser lists. This functionality helps understand the reach of browser support decisions by computing what percentage of users are covered by a given set of browsers.

Capabilities

Coverage Calculation

Calculate the total market coverage for a list of browsers.

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

Usage Examples:

const browserslist = require("browserslist");

// Calculate coverage for specific browsers
const browsers = ['chrome 88', 'firefox 85', 'safari 14'];
const globalCoverage = browserslist.coverage(browsers);
console.log(`Global coverage: ${globalCoverage}%`);
// => Global coverage: 78.3%

// Calculate coverage for browserslist result
const modernBrowsers = browserslist('last 2 versions, > 1%');
const coverage = browserslist.coverage(modernBrowsers);
console.log(`Coverage: ${coverage.toFixed(2)}%`);

// Coverage with country-specific stats
const usCoverage = browserslist.coverage(browsers, 'US');
console.log(`US coverage: ${usCoverage}%`);

// Coverage with custom statistics
const customStats = {
  'chrome 88': 25.5,
  'firefox 85': 15.2,
  'safari 14': 12.8
};
const customCoverage = browserslist.coverage(browsers, customStats);

Statistics Sources

The stats parameter accepts different types of statistics sources:

Global Statistics (default):

// Uses global browser usage statistics
const coverage = browserslist.coverage(browsers);
// Equivalent to:
const coverage = browserslist.coverage(browsers, 'global');

Country-specific Statistics:

// Two-letter country codes (uppercase)
const usCoverage = browserslist.coverage(browsers, 'US');
const jpCoverage = browserslist.coverage(browsers, 'JP');
const deCoverage = browserslist.coverage(browsers, 'DE');

// Full country names (lowercase)
const chinaCoverage = browserslist.coverage(browsers, 'china');
const russiaCoverage = browserslist.coverage(browsers, 'russia');

Custom Statistics from File:

// Load custom statistics from browserslist config
const myStatsCoverage = browserslist.coverage(browsers, 'my stats');

Custom Statistics Object:

// Direct statistics object
const customStats = {
  'chrome 88': 30.5,
  'chrome 87': 25.2,
  'firefox 85': 20.1,
  'safari 14': 15.8
};
const coverage = browserslist.coverage(browsers, customStats);

// Statistics with dataByBrowser format (common in analytics tools)
const analyticsStats = {
  dataByBrowser: {
    chrome: { '88': 30.5, '87': 25.2 },
    firefox: { '85': 20.1, '84': 18.5 },
    safari: { '14': 15.8, '13': 12.2 }
  }
};
const analyticsCoverage = browserslist.coverage(browsers, analyticsStats);

Usage Statistics Properties

Access to the underlying usage statistics used by browserslist:

/** Browser usage statistics */
browserslist.usage: {
  /** Global browser usage statistics */
  global: object;
  /** Custom usage statistics (loaded from files) */
  custom: object | null;
};

Usage Examples:

// Access global usage stats
console.log(browserslist.usage.global['chrome 88']);
// => 25.5 (percentage)

// Check if custom stats are loaded
if (browserslist.usage.custom) {
  console.log('Custom statistics available');
}

Custom Statistics Files

Browserslist can load custom usage statistics from JSON files:

browserslist-stats.json format:

{
  "chrome": {
    "88": 25.5,
    "87": 23.2
  },
  "firefox": {
    "85": 18.1,
    "84": 16.8
  }
}

dataByBrowser format (common in analytics tools):

{
  "dataByBrowser": {
    "chrome": {
      "88": 25.5,
      "87": 23.2
    },
    "firefox": {
      "85": 18.1,
      "84": 16.8
    }
  }
}

Error Handling

Coverage calculation can throw BrowserslistError for:

// Invalid statistics source
try {
  browserslist.coverage(browsers, 'my stats');
} catch (error) {
  // Throws if no custom statistics provided
  console.error(error.message); // "Custom usage statistics was not provided"
}

// Missing browser data
const coverage = browserslist.coverage(['unknown-browser 1']);
// Returns 0 for unknown browsers (no error thrown)

Practical Applications

Build Tool Integration:

// Check if browser support meets coverage requirements
const browsers = browserslist('> 1%, last 2 versions');
const coverage = browserslist.coverage(browsers);

if (coverage < 95) {
  console.warn(`Browser coverage is only ${coverage.toFixed(1)}%, consider expanding support`);
}

Regional Analysis:

// Compare coverage across different regions
const browsers = browserslist('defaults');
const regions = ['US', 'GB', 'DE', 'JP', 'CN'];

regions.forEach(region => {
  const coverage = browserslist.coverage(browsers, region);
  console.log(`${region}: ${coverage.toFixed(1)}%`);
});

Custom Analytics Integration:

// Use your own analytics data
const analyticsData = getAnalyticsData(); // Your analytics function
const supportedBrowsers = browserslist('> 0.1%');
const actualCoverage = browserslist.coverage(supportedBrowsers, analyticsData);

console.log(`Your users: ${actualCoverage.toFixed(1)}% coverage`);

Version

Tile

Files