Browser Installation

/**
 * Downloads and unpacks the browser archive according to InstallOptions
 * @param options - Installation configuration with unpack enabled (default)
 * @returns Promise resolving to InstalledBrowser instance
 */
function install(options: InstallOptions & {unpack?: true}): Promise<InstalledBrowser>;

/**
 * Downloads the browser archive without unpacking
 * @param options - Installation configuration with unpack disabled
 * @returns Promise resolving to absolute path of downloaded archive
 */
function install(options: InstallOptions & {unpack: false}): Promise<string>;

interface InstallOptions {
  /** Path to download browsers to */
  cacheDir: string;
  /** Target platform (auto-detected if not provided) */
  platform?: BrowserPlatform;
  /** Browser to install */
  browser: Browser;
  /** Build identifier for caching */
  buildId: string;
  /** Alias for the build ID (e.g., 'canary') */
  buildIdAlias?: string;
  /** Progress callback or 'default' for built-in progress bar */
  downloadProgressCallback?: 'default' | ((downloadedBytes: number, totalBytes: number) => void);
  /** Download host URL (uses default browser-specific URLs if not provided) */
  baseUrl?: string;
  /** Whether to unpack archives (default: true) */
  unpack?: boolean;
  /** Install system dependencies (default: false, Linux Chrome only) */
  installDeps?: boolean;
}

import { install, Browser, BrowserPlatform } from "@puppeteer/browsers";

// Install latest Chrome with default settings
const browser = await install({
  cacheDir: "./browsers-cache",
  browser: Browser.CHROME,
  buildId: "118.0.5993.70"
});

console.log("Installed at:", browser.path);
console.log("Executable:", browser.executablePath);

// Install with progress tracking
const browserWithProgress = await install({
  cacheDir: "./browsers-cache",
  browser: Browser.FIREFOX,
  buildId: "119.0",
  downloadProgressCallback: (downloaded, total) => {
    const percent = (downloaded / total * 100).toFixed(1);
    console.log(`Download progress: ${percent}%`);
  }
});

// Download archive without unpacking
const archivePath = await install({
  cacheDir: "./browsers-cache",
  browser: Browser.CHROMIUM,
  buildId: "1097615",
  unpack: false
});

console.log("Archive downloaded to:", archivePath);

/**
 * Uninstalls a browser from the cache directory
 * @param options - Uninstallation configuration
 */
function uninstall(options: UninstallOptions): Promise<void>;

interface UninstallOptions {
  /** Target platform (auto-detected if not provided) */
  platform?: BrowserPlatform;
  /** Path to cache directory */
  cacheDir: string;
  /** Browser to uninstall */
  browser: Browser;
  /** Build identifier to uninstall */
  buildId: string;
}

import { uninstall, Browser } from "@puppeteer/browsers";

// Uninstall specific browser version
await uninstall({
  cacheDir: "./browsers-cache",
  browser: Browser.CHROME,
  buildId: "118.0.5993.70"
});

console.log("Browser uninstalled successfully");

/**
 * Returns metadata about browsers installed in the cache directory
 * @param options - Query configuration
 * @returns Promise resolving to array of installed browser instances
 */
function getInstalledBrowsers(options: GetInstalledBrowsersOptions): Promise<InstalledBrowser[]>;

interface GetInstalledBrowsersOptions {
  /** Path to cache directory */
  cacheDir: string;
}

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

// List all installed browsers
const browsers = await getInstalledBrowsers({
  cacheDir: "./browsers-cache"
});

browsers.forEach(browser => {
  console.log(`${browser.browser}@${browser.buildId} (${browser.platform})`);
  console.log(`  Path: ${browser.path}`);
  console.log(`  Executable: ${browser.executablePath}`);
});

/**
 * Checks if a browser can be downloaded with given options
 * @param options - Installation configuration to check
 * @returns Promise resolving to boolean indicating download availability
 */
function canDownload(options: InstallOptions): Promise<boolean>;

import { canDownload, Browser } from "@puppeteer/browsers";

// Check if browser version is available for download
const isAvailable = await canDownload({
  cacheDir: "./browsers-cache",
  browser: Browser.CHROME,
  buildId: "118.0.5993.70"
});

if (isAvailable) {
  console.log("Browser is available for download");
} else {
  console.log("Browser version not found");
}

/**
 * Retrieves URL for downloading browser binary archive
 * @param browser - Browser type
 * @param platform - Target platform
 * @param buildId - Build identifier
 * @param baseUrl - Optional base URL override
 * @returns Download URL
 */
function getDownloadUrl(
  browser: Browser, 
  platform: BrowserPlatform, 
  buildId: string, 
  baseUrl?: string
): URL;

import { getDownloadUrl, Browser, BrowserPlatform } from "@puppeteer/browsers";

// Get download URL for specific browser
const url = getDownloadUrl(
  Browser.CHROME,
  BrowserPlatform.LINUX,
  "118.0.5993.70"
);

console.log("Download URL:", url.toString());

/**
 * Creates default progress callback for browser downloads
 * @param browser - Browser type
 * @param buildId - Build identifier
 * @returns Progress callback function with built-in progress bar
 */
function makeProgressCallback(
  browser: Browser, 
  buildId: string
): (downloadedBytes: number, totalBytes: number) => void;

import { install, makeProgressCallback, Browser } from "@puppeteer/browsers";

// Install with default progress callback
const progressCallback = makeProgressCallback(Browser.CHROME, "118.0.5993.70");

const browser = await install({
  cacheDir: "./browsers-cache",
  browser: Browser.CHROME,
  buildId: "118.0.5993.70",
  downloadProgressCallback: progressCallback
});