Implementation:Puppeteer Puppeteer BrowserProvider

Property	Value
sources	packages/browsers/src/provider.ts
domains	Browser Management, Download Provider Interface, Extensibility
last_updated	2026-02-12 00:00 GMT

Overview

Description

The BrowserProvider module defines the interface and utility functions for custom browser download provider implementations in the @puppeteer/browsers package. It provides an extensibility point that allows users to implement alternative download sources for browsers, such as corporate mirrors or Electron ChromeDriver builds.

The module exports three key items:

• DownloadOptions -- An interface specifying the browser, platform, and build ID for download operations
• BrowserProvider -- The core interface with four methods: supports(), getDownloadUrl(), getExecutablePath(), and getName()
• buildArchiveFilename -- A utility function for constructing standardized archive filenames

The BrowserProvider interface supports both synchronous and asynchronous implementations. Methods can return either direct values or Promises, allowing simple URL construction to be synchronous while version resolution requiring network requests can be asynchronous.

Custom providers carry an explicit warning: they are not officially supported by Puppeteer. Users implementing custom providers accept responsibility for binary compatibility, testing, and maintenance.

Usage

This module is used by the DefaultProvider as its implementation target and can be implemented by third-party code to provide alternative browser download sources. The buildArchiveFilename utility is available for constructing consistent archive names.

Code Reference

Source Location

packages/browsers/src/provider.ts

Signature

export interface DownloadOptions {
  browser: Browser;
  platform: BrowserPlatform;
  buildId: string;
}

export interface BrowserProvider {
  supports(options: DownloadOptions): Promise<boolean> | boolean;
  getDownloadUrl(options: DownloadOptions): Promise<URL | null> | URL | null;
  getExecutablePath(options: {
    browser: Browser;
    buildId: string;
    platform: BrowserPlatform;
  }): Promise<string> | string;
  getName(): string;
}

export function buildArchiveFilename(
  browser: Browser,
  platform: BrowserPlatform,
  buildId: string,
  extension?: string,
): string;

Import

import {type BrowserProvider, type DownloadOptions, buildArchiveFilename} from '@puppeteer/browsers';

I/O Contract

DownloadOptions Interface

Property	Type	Description
browser	Browser	The browser product to download
platform	BrowserPlatform	The target OS/architecture combination
buildId	string	The version or alias to download (e.g., "131.0.6778.109" or "stable")

BrowserProvider Interface Methods

Method	Parameters	Return Type	Description
supports	DownloadOptions	boolean	Check if this provider supports the given browser/platform combination
getDownloadUrl	DownloadOptions	null> | URL | null	Get the download URL; returns null if the build ID cannot be resolved
getExecutablePath	{browser, buildId, platform}	string	Get the relative path to the executable within the extracted archive
getName	none	string	Get the name of this provider for logging and error messages

buildArchiveFilename

Parameter	Type	Description
browser	Browser	Browser product identifier
platform	BrowserPlatform	Platform identifier
buildId	string	Build/version ID
extension	string (optional)	File extension, defaults to 'zip'
Returns	string	Filename in format {browser}-{platform}-{buildId}.{extension}

Usage Examples

import {
  type BrowserProvider,
  type DownloadOptions,
  Browser,
  BrowserPlatform,
  buildArchiveFilename,
} from '@puppeteer/browsers';

// Implement a custom provider for Electron ChromeDriver
class ElectronDownloader implements BrowserProvider {
  supports(options: DownloadOptions): boolean {
    return options.browser === Browser.CHROMEDRIVER;
  }

  getDownloadUrl(options: DownloadOptions): URL {
    const platform = mapToPlatform(options.platform);
    return new URL(
      `v${options.buildId}/chromedriver-v${options.buildId}-${platform}.zip`,
      'https://github.com/electron/electron/releases/download/',
    );
  }

  getExecutablePath(options: {browser: Browser; buildId: string; platform: BrowserPlatform}): string {
    const ext = options.platform.includes('win') ? '.exe' : '';
    return `chromedriver/chromedriver${ext}`;
  }

  getName(): string {
    return 'ElectronDownloader';
  }
}

// Use the buildArchiveFilename utility
const filename = buildArchiveFilename(
  Browser.CHROME,
  BrowserPlatform.LINUX,
  '131.0.6778.109'
);
// => 'chrome-linux-131.0.6778.109.zip'

const tarFilename = buildArchiveFilename(
  Browser.FIREFOX,
  BrowserPlatform.LINUX,
  'nightly_135.0a1',
  'tar.xz'
);
// => 'firefox-linux-nightly_135.0a1.tar.xz'

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime