CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-puppeteer--browsers

Download, manage, and launch browsers (Chrome, Chromium, Firefox) and drivers (ChromeDriver) for testing and automation

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

cli.mddocs/

Command Line Interface

Full-featured CLI for browser management operations including installation, launching, listing, and cleanup. Provides complete access to all browser management functionality through command-line interface with interactive features and comprehensive help system.

Capabilities

CLI Class

Main command-line interface class providing browser management operations through command-line arguments.

/**
 * Command-line interface for browser management
 */
class CLI {
  /**
   * Create CLI instance with configuration options
   * @param opts - Cache path string or configuration options
   * @param rl - Optional readline interface for interactive features
   */
  constructor(opts?: string | CLIOptions, rl?: readline.Interface);
  
  /**
   * Execute CLI with provided command-line arguments
   * @param argv - Command line arguments array (typically process.argv)
   * @returns Promise resolving when command execution completes
   */
  run(argv: string[]): Promise<void>;
}

interface CLIOptions {
  /** Cache directory path */
  cachePath?: string;
  /** Script name for help text */
  scriptName?: string;
  /** Version string */
  version?: string;
  /** Command prefix configuration */
  prefixCommand?: {
    cmd: string;
    description: string;
  };
  /** Allow cache path override via arguments */
  allowCachePathOverride?: boolean;
  /** Pinned browser configurations */
  pinnedBrowsers?: Partial<Record<Browser, {
    buildId: string;
    skipDownload: boolean;
  }>>;
}

Usage Examples:

import { CLI } from "@puppeteer/browsers";

// Basic CLI usage
const cli = new CLI("./browsers-cache");
await cli.run(process.argv);

// Advanced CLI configuration
const advancedCli = new CLI({
  cachePath: "./custom-cache",
  scriptName: "my-browser-manager",
  version: "1.0.0",
  allowCachePathOverride: true,
  pinnedBrowsers: {
    [Browser.CHROME]: {
      buildId: "118.0.5993.70",
      skipDownload: false
    }
  }
});

await advancedCli.run([
  "node", "script.js", 
  "install", "chrome@stable"
]);

Available Commands

Install Command

Downloads and installs browsers with support for version specifications, platform targeting, and progress tracking.

Command Syntax:

npx @puppeteer/browsers install [browser[@version]] [options]

Options:

  • --platform <platform> - Target platform (linux, mac, win32, etc.)
  • --path <path> - Cache directory path
  • --base-url <url> - Custom download base URL
  • --install-deps - Install system dependencies (Linux Chrome only)

Usage Examples:

# Install latest stable Chrome
npx @puppeteer/browsers install chrome@stable

# Install specific Chrome version
npx @puppeteer/browsers install chrome@118.0.5993.70

# Install Chrome for specific platform
npx @puppeteer/browsers install chrome@stable --platform linux

# Install Firefox nightly
npx @puppeteer/browsers install firefox@nightly

# Install ChromeDriver
npx @puppeteer/browsers install chromedriver@stable

# Install with system dependencies (requires root on Linux)
npx @puppeteer/browsers install chrome@stable --install-deps

# Install to custom cache directory
npx @puppeteer/browsers install chrome@stable --path ./my-cache

Launch Command

Launches installed browsers with customizable arguments and configuration options.

Command Syntax:

npx @puppeteer/browsers launch <browser[@version]> [options] [-- browser-args...]

Options:

  • --detached - Launch in detached mode
  • --system - Use system-installed browser instead of cached
  • --dumpio - Forward browser output to console

Usage Examples:

# Launch installed Chrome
npx @puppeteer/browsers launch chrome@stable

# Launch with browser arguments
npx @puppeteer/browsers launch chrome@stable -- --headless --no-sandbox

# Launch system Chrome
npx @puppeteer/browsers launch chrome@stable --system

# Launch detached browser
npx @puppeteer/browsers launch firefox@latest --detached

# Launch with output forwarding
npx @puppeteer/browsers launch chrome@stable --dumpio -- --remote-debugging-port=9222

List Command

Lists all installed browsers in the cache directory with detailed information.

Command Syntax:

npx @puppeteer/browsers list [options]

Options:

  • --path <path> - Cache directory path

Usage Examples:

# List all installed browsers
npx @puppeteer/browsers list

# List browsers in custom cache directory
npx @puppeteer/browsers list --path ./my-cache

Example Output:

chrome@118.0.5993.70 linux /path/to/cache/chrome/linux-118.0.5993.70/chrome-linux64/chrome
firefox@119.0 linux /path/to/cache/firefox/linux-119.0/firefox/firefox
chromedriver@118.0.5993.70 linux /path/to/cache/chromedriver/linux-118.0.5993.70/chromedriver

Clear Command

Removes all installed browsers from the cache directory with interactive confirmation.

Command Syntax:

npx @puppeteer/browsers clear [options]

Options:

  • --path <path> - Cache directory path

Usage Examples:

# Clear all browsers (with confirmation prompt)
npx @puppeteer/browsers clear

# Clear custom cache directory
npx @puppeteer/browsers clear --path ./my-cache

Browser Version Specifications

The CLI supports flexible browser version specifications:

Version Formats

  • Release Channels: chrome@stable, firefox@nightly, chromedriver@beta
  • Specific Versions: chrome@118.0.5993.70, firefox@119.0
  • Milestone Versions: chrome@118 (latest in milestone)
  • Latest: chrome@latest, firefox@latest

Supported Browsers and Channels

Chrome:

  • stable - Latest stable release
  • beta - Latest beta release
  • dev - Latest dev channel release
  • canary - Latest canary release
  • Specific versions: 118.0.5993.70
  • Milestones: 118, 119

Firefox:

  • stable - Latest stable release
  • nightly - Latest nightly build
  • devedition - Developer edition
  • beta - Beta channel
  • esr - Extended Support Release
  • Specific versions: 119.0, 118.0.1

ChromeDriver:

  • Follows Chrome versioning
  • stable, beta, dev, canary
  • Specific versions matching Chrome

Chromium:

  • Snapshot builds from tip-of-tree
  • Specific revision numbers: 1097615

Chrome Headless Shell:

  • Follows Chrome versioning
  • Same channels as Chrome

CLI Help System

The CLI provides comprehensive help for all commands:

# General help
npx @puppeteer/browsers --help

# Command-specific help
npx @puppeteer/browsers install --help
npx @puppeteer/browsers launch --help
npx @puppeteer/browsers list --help
npx @puppeteer/browsers clear --help

Configuration and Customization

Cache Directory Configuration

Default cache directory follows platform conventions:

  • Linux/macOS: ~/.cache/puppeteer/browsers
  • Windows: %LOCALAPPDATA%/puppeteer/browsers

Override with --path option or PUPPETEER_CACHE_DIR environment variable.

Environment Variables

  • PUPPETEER_CACHE_DIR - Default cache directory
  • HTTP_PROXY / HTTPS_PROXY - Proxy configuration for downloads
  • NO_PROXY - Proxy bypass configuration

Version Specification

Use npx with specific versions:

# Always use latest from registry
npx @puppeteer/browsers@latest install chrome@stable

# Use specific package version
npx @puppeteer/browsers@2.10.8 install chrome@stable

# Auto-confirm installation
npx --yes @puppeteer/browsers@latest install chrome@stable

Programmatic CLI Usage

Embed the CLI in Node.js applications:

import { CLI } from "@puppeteer/browsers";

async function manageBrowsers() {
  const cli = new CLI({
    cachePath: "./app-browsers",
    scriptName: "app-browser-manager"
  });
  
  // Install Chrome programmatically
  await cli.run(["node", "app.js", "install", "chrome@stable"]);
  
  // List installed browsers
  await cli.run(["node", "app.js", "list"]);
  
  // Launch browser with custom args
  await cli.run([
    "node", "app.js", 
    "launch", "chrome@stable", 
    "--", "--headless", "--no-sandbox"
  ]);
}

manageBrowsers().catch(console.error);

Error Handling and Debugging

The CLI provides detailed error messages and debugging information:

Common Error Scenarios

Installation Errors:

  • Network connectivity issues
  • Disk space problems
  • Permission errors
  • Invalid version specifications

Launch Errors:

  • Browser not installed
  • Invalid executable paths
  • System compatibility issues
  • Process startup failures

Cache Errors:

  • Directory access problems
  • Corrupted cache metadata
  • Insufficient permissions

Debug Output

Enable debug output with environment variables:

# Debug browser installation
DEBUG=puppeteer:browsers:install npx @puppeteer/browsers install chrome@stable

# Debug browser launching
DEBUG=puppeteer:browsers:launcher npx @puppeteer/browsers launch chrome@stable

# Debug cache operations
DEBUG=puppeteer:browsers:cache npx @puppeteer/browsers list

Integration Examples

CI/CD Pipeline

#!/bin/bash
# Install specific browser versions for testing
npx @puppeteer/browsers install chrome@118.0.5993.70
npx @puppeteer/browsers install firefox@119.0

# Run tests with installed browsers
npm test

Docker Container

FROM node:18
RUN npx @puppeteer/browsers install chrome@stable --install-deps
COPY . .
CMD ["npm", "start"]

Development Workflow

# Setup development environment
npx @puppeteer/browsers install chrome@stable
npx @puppeteer/browsers install chrome@canary
npx @puppeteer/browsers install firefox@nightly

# Launch for debugging
npx @puppeteer/browsers launch chrome@stable -- --remote-debugging-port=9222

Install with Tessl CLI

npx tessl i tessl/npm-puppeteer--browsers

docs

browser-data.md

cache.md

cli.md

index.md

installation.md

launching.md

tile.json