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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Coverage Analysis

Name: tessl/npm-browserslist
Author: tessl

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`);