or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser-lifecycle.mdindex.mdplugin-management.md
tile.json

tessl/npm-puppeteer-extra

Modular plugin framework to teach puppeteer new tricks through plugins.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/puppeteer-extra@2.1.x

To install, run

npx @tessl/cli install tessl/npm-puppeteer-extra@2.1.0

index.mddocs/

Puppeteer Extra

Puppeteer Extra is a modular plugin framework that acts as a drop-in replacement for Puppeteer while extending it with additional functionality through a clean plugin architecture. It enables developers to compose multiple plugins to enhance browser automation capabilities including stealth mode, user agent anonymization, resource blocking, reCAPTCHA solving, and developer tools integration.

Package Information

  • Package Name: puppeteer-extra
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install puppeteer puppeteer-extra

Core Imports

const puppeteer = require('puppeteer-extra');

For ES modules:

import puppeteer from 'puppeteer-extra';

Note: The module exports a singleton PuppeteerExtra instance, not the class itself.

Basic Usage

const puppeteer = require('puppeteer-extra');

// Add plugins before browser launch
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
puppeteer.use(StealthPlugin());

// Use exactly like regular Puppeteer
const browser = await puppeteer.launch({ headless: false });
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();

Architecture

Puppeteer Extra is built around several key components:

  • Plugin Framework: Central registry system for managing and executing plugins
  • Lifecycle Hooks: Plugin integration points during browser launch and connection
  • Dependency Management: Automatic resolution and installation of plugin dependencies
  • Drop-in Compatibility: Full Puppeteer API pass-through with no breaking changes
  • Page Creation Patching: Built-in workarounds for Puppeteer timing issues

Capabilities

Plugin Management

Core functionality for registering and managing plugins that extend Puppeteer's capabilities.

/**
 * Register a plugin with the framework
 * @param plugin - Plugin instance extending PuppeteerExtraPlugin
 * @returns The PuppeteerExtra instance for method chaining
 */
use(plugin): this;

/**
 * Get all registered plugins
 * @returns Array of registered plugin instances
 */
get plugins(): Array<PuppeteerExtraPlugin>;

/**
 * Collect exposed data from all registered plugins
 * @param name - Optional filter by plugin name
 * @returns Array of plugin data objects
 */
getPluginData(name?: string): Array<Object>;

Plugin Management

Browser Lifecycle

Enhanced browser launch and connection methods with plugin lifecycle integration.

/**
 * Launch a new browser instance with plugin lifecycle support
 * @param options - Regular Puppeteer launch options
 * @returns Promise resolving to Browser instance
 */
launch(options?: Object): Promise<Puppeteer.Browser>;

/**
 * Connect to existing Chromium instance with plugin lifecycle support
 * @param options - Connection options with browserWSEndpoint and ignoreHTTPSErrors
 * @returns Promise resolving to Browser instance
 */
connect(options?: {
  browserWSEndpoint: string;
  ignoreHTTPSErrors?: boolean;
}): Promise<Puppeteer.Browser>;

Browser Lifecycle

Puppeteer Pass-through Methods

Standard Puppeteer methods that are passed through unchanged for full compatibility.

/**
 * Get the path to the bundled Chromium executable
 * @returns Path to Chromium executable
 */
executablePath(): string;

/**
 * Get default launch arguments for Chromium
 * @returns Array of default launch arguments
 */
defaultArgs(): Array<string>;

/**
 * Create a browser fetcher for downloading Chromium
 * @param options - Fetcher configuration options
 * @returns BrowserFetcher instance
 */
createBrowserFetcher(options?: Object): PuppeteerBrowserFetcher;

Types

/**
 * Base class that all plugins must extend
 */
class PuppeteerExtraPlugin {
  /** Plugin name identifier */
  name: string;
  /** Set of plugin requirements ('launch', 'headful', 'dataFromPlugins', 'runLast') */
  requirements: Set<string>;
  /** Set of plugin dependencies (auto-resolved plugin names) */
  dependencies: Set<string>;
  /** Plugin-specific data for sharing with other plugins */
  data: Array<{ name: string; value: any }>;
  /** Plugin configuration options */
  opts: Object;
  /** Debug logger function */
  debug: Function;
  /** Whether this is a valid PuppeteerExtraPlugin */
  _isPuppeteerExtraPlugin: boolean;
}

/**
 * Puppeteer Browser Fetcher for downloading Chromium
 */
interface PuppeteerBrowserFetcher {
  /** Download a specific revision of Chromium */
  download(revision: string): Promise<Object>;
  /** Get path to downloaded revision */
  revisionInfo(revision: string): Object;
  /** Remove a downloaded revision */
  remove(revision: string): Promise<void>;
  /** List all downloaded revisions */
  localRevisions(): Array<string>;
}

/**
 * Plugin configuration options
 */
interface PluginOptions {
  [key: string]: any;
}

/**
 * Plugin data structure for sharing between plugins
 */
interface PluginData {
  name: string;
  value: any;
}

Error Handling

Puppeteer Extra maintains the same error handling patterns as standard Puppeteer. Plugin-related errors include:

  • Plugin Registration Errors: Invalid plugins or missing dependencies
  • Requirement Conflicts: Plugins incompatible with current launch mode (headless/headful)
  • Dependency Resolution: Missing required plugin packages

Common Plugins

Popular plugins that extend Puppeteer Extra functionality:

  • puppeteer-extra-plugin-stealth: Applies evasion techniques to avoid detection
  • puppeteer-extra-plugin-recaptcha: Automatically solves reCAPTCHAs
  • puppeteer-extra-plugin-anonymize-ua: Anonymizes user agent strings
  • puppeteer-extra-plugin-block-resources: Blocks images, CSS, and other resources
  • puppeteer-extra-plugin-devtools: Enables remote debugging capabilities