Update Browserslist DB

Update Browserslist DB is a CLI tool that updates the caniuse-lite database to refresh target browsers from Browserslist configuration. It automatically detects package managers (npm, yarn, pnpm, bun) and updates the caniuse-lite dependency to ensure browser queries use the most current browser data, reducing unnecessary polyfills and improving website performance.

Package Information

• Package Name: update-browserslist-db
• Package Type: npm
• Language: JavaScript with TypeScript definitions
• Installation: npm install update-browserslist-db or npx update-browserslist-db@latest

Core Imports

const updateDb = require("update-browserslist-db");

For TypeScript:

import updateDb = require("update-browserslist-db");
// or with type annotations
const updateDb: (print?: (str: string) => void) => void = require("update-browserslist-db");

Basic Usage

CLI Usage

# Update caniuse-lite database
npx update-browserslist-db@latest

# Show help
npx update-browserslist-db --help
npx update-browserslist-db -h

# Show version
npx update-browserslist-db --version
npx update-browserslist-db -v

Programmatic Usage

const updateDb = require("update-browserslist-db");

// Use default stdout output
updateDb();

// Custom output handling
updateDb((message) => {
  console.log("Custom:", message);
});

Architecture

The package consists of several key components:

• Main Function: updateDb() orchestrates the entire update process
• Package Manager Detection: Automatically detects npm, yarn, pnpm, or bun lockfiles
• Version Management: Fetches latest caniuse-lite version and compares with installed versions
• Lockfile Updates: Updates package manager lockfiles with new caniuse-lite version
• Browser Analysis: Shows target browser changes when browserslist is available
• Error Handling: Custom error types for different failure scenarios

Capabilities

Database Update

Updates the caniuse-lite database to the latest version, ensuring up-to-date browser data for tools like Autoprefixer and Babel.

/**
 * Run update and print output to terminal.
 * @param {function} [print] - Optional function to handle output strings
 */
function updateDb(print?: (str: string) => void): void

The function:

• Detects the package manager being used (npm, yarn, pnpm, bun)
• Fetches the latest caniuse-lite version information
• Updates the lockfile to use the latest version
• Shows browser target changes if browserslist is available
• Handles errors gracefully with custom error types

Usage Examples:

const updateDb = require("update-browserslist-db");

// Basic usage with default output
updateDb();

// Custom output handling for logging
updateDb((message) => {
  // Strip ANSI color codes if needed
  const cleanMessage = message.replace(/\x1b\[\d+m/g, '');
  logger.info('Browserslist update:', cleanMessage);
});

// Capture output for processing
let outputBuffer = '';
updateDb((message) => {
  outputBuffer += message;
});

Error Handling

Custom error class for browserslist update-specific errors. This error is thrown by the updateDb() function when update-specific issues occur.

/**
 * Custom error class for browserslist update-specific errors
 * @param {string} message - Error message
 */
function BrowserslistUpdateError(message: string): BrowserslistUpdateError

// Error instance properties:
interface BrowserslistUpdateErrorInstance extends Error {
  name: "BrowserslistUpdateError";
  message: string;          // Descriptive error message
  browserslist: true;       // Marker property to identify browserslist errors
}

Common error scenarios:

• Missing package.json file
• No lockfile found (missing npm/yarn/pnpm installation)
• Package manager command execution failures
• Browserslist configuration errors

Usage Example:

const updateDb = require("update-browserslist-db");

try {
  updateDb();
} catch (error) {
  if (error.name === 'BrowserslistUpdateError') {
    console.error('Browserslist update failed:', error.message);
    // Handle browserslist-specific errors
  } else {
    throw error; // Re-throw other errors
  }
}

Supported Package Managers

The tool automatically detects and supports:

• npm: via package-lock.json or npm-shrinkwrap.json
• yarn v1: via yarn.lock (manual lockfile update)
• yarn v2+: via yarn.lock (uses yarn up -R caniuse-lite)
• pnpm: via pnpm-lock.yaml (uses pnpm up caniuse-lite)
• bun: via bun.lock or bun.lockb (uses bun update caniuse-lite)

Error Scenarios

The tool handles several error conditions gracefully:

1. Missing package.json: "Cannot find package.json. Is this the right directory to run npx update-browserslist-db in?"
2. Missing lockfile: "No lockfile found. Run 'npm install', 'yarn install' or 'pnpm install'"
3. Missing browserslist: Shows gray message about installing browserslist for target browser changes
4. Package manager errors: Shows command output and suggests manual execution
5. Browser list retrieval errors: Shows warning that target browser changes won't be shown

Internal Data Structures

The following data structures are used internally by the package:

// Output handler function type
// function(str: string) => void

// Package manager detection result
// {
//   file: string,           // Path to lockfile
//   mode: string,           // "npm" | "yarn" | "pnpm" | "bun"
//   content?: string,       // Lockfile content (when loaded)
//   version?: number        // Yarn lockfile version (1 or 2)
// }

// Latest package version information  
// {
//   version: string,        // Latest version number
//   dist: {
//     tarball: string,      // Download URL
//     integrity?: string    // SRI hash (optional)
//   }
// }

// Browser list data structure
// {
//   [browser: string]: string[]  // Browser name -> array of versions
// }

TypeScript Support

The package includes complete TypeScript definitions:

/**
 * Run update and print output to terminal.
 */
declare function updateDb(print?: (str: string) => void): void

export = updateDb