0
# Puppeteer Extra
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: puppeteer-extra
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install puppeteer puppeteer-extra`
10

11
## Core Imports
12

13
```javascript
14
const puppeteer = require('puppeteer-extra');
15
```
16

17
For ES modules:
18

19
```javascript
20
import puppeteer from 'puppeteer-extra';
21
```
22

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

25
## Basic Usage
26

27
```javascript
28
const puppeteer = require('puppeteer-extra');
29

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

34
// Use exactly like regular Puppeteer
35
const browser = await puppeteer.launch({ headless: false });
36
const page = await browser.newPage();
37
await page.goto('https://example.com');
38
await browser.close();
39
```
40

41
## Architecture
42

43
Puppeteer Extra is built around several key components:
44

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

51
## Capabilities
52

53
### Plugin Management
54

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

57
```javascript { .api }
58
/**
59
 * Register a plugin with the framework
60
 * @param plugin - Plugin instance extending PuppeteerExtraPlugin
61
 * @returns The PuppeteerExtra instance for method chaining
62
 */
63
use(plugin): this;
64

65
/**
66
 * Get all registered plugins
67
 * @returns Array of registered plugin instances
68
 */
69
get plugins(): Array<PuppeteerExtraPlugin>;
70

71
/**
72
 * Collect exposed data from all registered plugins
73
 * @param name - Optional filter by plugin name
74
 * @returns Array of plugin data objects
75
 */
76
getPluginData(name?: string): Array<Object>;
77
```
78

79
[Plugin Management](./plugin-management.md)
80

81
### Browser Lifecycle
82

83
Enhanced browser launch and connection methods with plugin lifecycle integration.
84

85
```javascript { .api }
86
/**
87
 * Launch a new browser instance with plugin lifecycle support
88
 * @param options - Regular Puppeteer launch options
89
 * @returns Promise resolving to Browser instance
90
 */
91
launch(options?: Object): Promise<Puppeteer.Browser>;
92

93
/**
94
 * Connect to existing Chromium instance with plugin lifecycle support
95
 * @param options - Connection options with browserWSEndpoint and ignoreHTTPSErrors
96
 * @returns Promise resolving to Browser instance
97
 */
98
connect(options?: {
99
  browserWSEndpoint: string;
100
  ignoreHTTPSErrors?: boolean;
101
}): Promise<Puppeteer.Browser>;
102
```
103

104
[Browser Lifecycle](./browser-lifecycle.md)
105

106
### Puppeteer Pass-through Methods
107

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

110
```javascript { .api }
111
/**
112
 * Get the path to the bundled Chromium executable
113
 * @returns Path to Chromium executable
114
 */
115
executablePath(): string;
116

117
/**
118
 * Get default launch arguments for Chromium
119
 * @returns Array of default launch arguments
120
 */
121
defaultArgs(): Array<string>;
122

123
/**
124
 * Create a browser fetcher for downloading Chromium
125
 * @param options - Fetcher configuration options
126
 * @returns BrowserFetcher instance
127
 */
128
createBrowserFetcher(options?: Object): PuppeteerBrowserFetcher;
129
```
130

131
## Types
132

133
```javascript { .api }
134
/**
135
 * Base class that all plugins must extend
136
 */
137
class PuppeteerExtraPlugin {
138
  /** Plugin name identifier */
139
  name: string;
140
  /** Set of plugin requirements ('launch', 'headful', 'dataFromPlugins', 'runLast') */
141
  requirements: Set<string>;
142
  /** Set of plugin dependencies (auto-resolved plugin names) */
143
  dependencies: Set<string>;
144
  /** Plugin-specific data for sharing with other plugins */
145
  data: Array<{ name: string; value: any }>;
146
  /** Plugin configuration options */
147
  opts: Object;
148
  /** Debug logger function */
149
  debug: Function;
150
  /** Whether this is a valid PuppeteerExtraPlugin */
151
  _isPuppeteerExtraPlugin: boolean;
152
}
153

154
/**
155
 * Puppeteer Browser Fetcher for downloading Chromium
156
 */
157
interface PuppeteerBrowserFetcher {
158
  /** Download a specific revision of Chromium */
159
  download(revision: string): Promise<Object>;
160
  /** Get path to downloaded revision */
161
  revisionInfo(revision: string): Object;
162
  /** Remove a downloaded revision */
163
  remove(revision: string): Promise<void>;
164
  /** List all downloaded revisions */
165
  localRevisions(): Array<string>;
166
}
167

168
/**
169
 * Plugin configuration options
170
 */
171
interface PluginOptions {
172
  [key: string]: any;
173
}
174

175
/**
176
 * Plugin data structure for sharing between plugins
177
 */
178
interface PluginData {
179
  name: string;
180
  value: any;
181
}
182
```
183

184
## Error Handling
185

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

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

192
## Common Plugins
193

194
Popular plugins that extend Puppeteer Extra functionality:
195

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