Implementation:Puppeteer Puppeteer BrowserLauncher

Property	Value
sources	packages/puppeteer-core/src/node/BrowserLauncher.ts
domains	Node, Browser Lifecycle, Launch
last_updated	2026-02-12 00:00 GMT

Overview

Description

The BrowserLauncher abstract class is the core engine for launching browser instances in Puppeteer's Node.js environment. It orchestrates the entire browser launch lifecycle: computing launch arguments, spawning the browser process, establishing protocol connections (CDP via WebSocket, CDP via pipe, or WebDriver BiDi), and creating the Browser API object.

Key behaviors of the launch method:

1. Extracts and applies default values for all LaunchOptions (timeout, viewport, signal handling, etc.).
2. Delegates to the abstract computeLaunchArguments method (implemented by Chrome/Firefox-specific subclasses) to determine the executable path, arguments, and user data directory.
3. Validates that the executable path exists on the filesystem.
4. Spawns the browser process using @puppeteer/browsers launch function.
5. Establishes a protocol connection based on the browser type and configuration:
   • For Firefox: creates a native WebDriver BiDi connection.
   • For Chrome with pipe: creates a CDP connection over stdio pipes.
   • For Chrome with WebSocket: creates a CDP connection over WebSocket.
   • If WebDriver BiDi protocol is requested for Chrome, creates a BiDi-over-CDP bridge.
6. Handles error cases including locked profile directories, missing X server for headful mode, and timeout errors.
7. Optionally installs extensions and waits for the initial page target.

The class also provides resolveExecutablePath, which resolves the browser executable by checking the Puppeteer configuration, then falling back to the @puppeteer/browsers computeExecutablePath using the configured cache directory and browser version.

Usage

BrowserLauncher is not used directly. Concrete subclasses (ChromeLauncher and FirefoxLauncher) extend it and implement the abstract methods. Users interact with it through puppeteer.launch().

Code Reference

Source Location

packages/puppeteer-core/src/node/BrowserLauncher.ts

Signature

export interface ResolvedLaunchArgs {
  isTempUserDataDir: boolean;
  userDataDir: string;
  executablePath: string;
  args: string[];
}

export abstract class BrowserLauncher {
  puppeteer: PuppeteerNode;

  constructor(puppeteer: PuppeteerNode, browser: SupportedBrowser);

  get browser(): SupportedBrowser;

  async launch(options?: LaunchOptions): Promise<Browser>;

  abstract executablePath(channel?: ChromeReleaseChannel, validatePath?: boolean): string;
  abstract defaultArgs(object: LaunchOptions): string[];

  protected abstract computeLaunchArguments(options: LaunchOptions): Promise<ResolvedLaunchArgs>;
  protected abstract cleanUserDataDir(path: string, opts: {isTemp: boolean}): Promise<void>;

  protected async closeBrowser(browserProcess: ReturnType<typeof launch>, cdpConnection?: Connection): Promise<void>;
  protected async waitForPageTarget(browser: Browser, timeout: number): Promise<void>;
  protected async createCdpSocketConnection(browserProcess: ..., opts: ...): Promise<Connection>;
  protected async createCdpPipeConnection(browserProcess: ..., opts: ...): Promise<Connection>;
  protected async createBiDiOverCdpBrowser(browserProcess: ..., cdpConnection: ..., closeCallback: ..., opts: ...): Promise<Browser>;
  protected async createBiDiBrowser(browserProcess: ..., closeCallback: ..., opts: ...): Promise<Browser>;
  protected getProfilePath(): string;
  resolveExecutablePath(headless?: boolean | 'shell', validatePath?: boolean): string;
}

Import

import {BrowserLauncher} from '../node/BrowserLauncher.js';

I/O Contract

Parameter	Type	Description
options	LaunchOptions	Full set of browser launch options including timeout, headless mode, args, etc.
options.dumpio	boolean	Pipe browser stdout/stderr to process (default: false)
options.handleSIGINT	boolean	Close browser on Ctrl+C (default: true)
options.timeout	number	Max time in ms to wait for browser start (default: 30000)
options.protocol	'webDriverBiDi'	Communication protocol (Firefox defaults to webDriverBiDi)
options.defaultViewport	null	Default viewport dimensions

Return	Type	Description
Browser instance	Promise<Browser>	A connected, ready-to-use Browser object
executablePath	string	Resolved path to the browser executable

Usage Examples

// Typically accessed through puppeteer.launch(), not directly
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  timeout: 60000,
  args: ['--no-sandbox'],
});

const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime