0
# Plugin Management
1

2
Core functionality for registering and managing plugins that extend Puppeteer's capabilities through the plugin framework.
3

4
## Capabilities
5

6
### Plugin Registration
7

8
Register plugins with the framework to extend Puppeteer functionality.
9

10
```javascript { .api }
11
/**
12
 * Register a plugin with the framework
13
 * @param plugin - Plugin instance extending PuppeteerExtraPlugin base class
14
 * @returns The PuppeteerExtra instance for method chaining
15
 */
16
use(plugin): this;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const puppeteer = require('puppeteer-extra');
23

24
// Register stealth plugin with default settings
25
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
26
puppeteer.use(StealthPlugin());
27

28
// Register user agent plugin with custom options
29
const UserAgentPlugin = require('puppeteer-extra-plugin-anonymize-ua');
30
puppeteer.use(UserAgentPlugin({ makeWindows: true }));
31

32
// Chain multiple plugin registrations
33
puppeteer
34
  .use(StealthPlugin())
35
  .use(UserAgentPlugin())
36
  .use(require('puppeteer-extra-plugin-block-resources')());
37
```
38

39
### Plugin Introspection
40

41
Access registered plugins and their data.
42

43
```javascript { .api }
44
/**
45
 * Get all registered plugins
46
 * @returns Array of registered plugin instances
47
 */
48
get plugins(): Array<PuppeteerExtraPlugin>;
49

50
/**
51
 * Collect exposed data from all registered plugins
52
 * @param name - Optional filter by plugin name property
53
 * @returns Array of plugin data objects, flattened from all plugins
54
 */
55
getPluginData(name?: string): Array<Object>;
56
```
57

58
**Usage Examples:**
59

60
```javascript
61
// Get all registered plugins
62
const allPlugins = puppeteer.plugins;
63
console.log(`Registered ${allPlugins.length} plugins`);
64

65
// Get plugin data (used by plugins that need data from other plugins)
66
const allData = puppeteer.getPluginData();
67
const stealthData = puppeteer.getPluginData('stealth');
68
```
69

70
### Plugin Requirements and Dependencies
71

72
Plugins can declare requirements and dependencies that are automatically managed.
73

74
```javascript { .api }
75
/**
76
 * Base plugin class with requirement and dependency management
77
 */
78
class PuppeteerExtraPlugin {
79
  /** Unique plugin name identifier */
80
  name: string;
81
  
82
  /** Set of plugin requirements (e.g., 'headful', 'launch', 'runLast') */
83
  requirements: Set<string>;
84
  
85
  /** Set of plugin dependencies (auto-resolved) */
86
  dependencies: Set<string>;
87
  
88
  /** Plugin-specific data for sharing with other plugins */
89
  data: any;
90
  
91
  /** Whether this is a valid PuppeteerExtraPlugin */
92
  _isPuppeteerExtraPlugin: boolean;
93
}
94
```
95

96
**Plugin Requirements:**
97

98
- `"headful"` - Plugin requires headful mode (not compatible with headless)
99
- `"launch"` - Plugin only works with `launch()`, not `connect()`
100
- `"runLast"` - Plugin should be executed after other plugins
101
- `"dataFromPlugins"` - Plugin needs access to data from other plugins
102

103
**Usage Examples:**
104

105
```javascript
106
// Example plugin with requirements
107
class CustomPlugin extends PuppeteerExtraPlugin {
108
  constructor(opts = {}) {
109
    super(opts);
110
    this.name = 'custom-plugin';
111
    this.requirements = new Set(['headful', 'launch']);
112
    this.dependencies = new Set(['stealth']); // Auto-loads stealth plugin
113
  }
114
}
115

116
// Framework automatically handles requirements checking
117
puppeteer.use(new CustomPlugin());
118
const browser = await puppeteer.launch({ headless: true }); // Warns about headful requirement
119
```
120

121
### Automatic Dependency Resolution
122

123
The framework automatically installs and registers missing plugin dependencies.
124

125
```javascript { .api }
126
/**
127
 * Automatically resolve and install missing plugin dependencies
128
 * Dependencies are resolved recursively and installed on-demand
129
 */
130
resolvePluginDependencies(): void;
131
```
132

133
**Usage Examples:**
134

135
```javascript
136
// Plugin declares dependency on 'stealth' plugin
137
class MyPlugin extends PuppeteerExtraPlugin {
138
  constructor() {
139
    super();
140
    this.name = 'my-plugin';
141
    this.dependencies = new Set(['stealth']); // Will auto-install puppeteer-extra-plugin-stealth
142
  }
143
}
144

145
// Framework automatically installs and registers the stealth plugin
146
puppeteer.use(new MyPlugin());
147
// No need to manually install or require the stealth plugin
148
```
149

150
### Plugin Ordering
151

152
Plugins can specify execution order requirements for proper functionality.
153

154
```javascript { .api }
155
/**
156
 * Order plugins based on requirements like 'runLast'
157
 * Ensures plugins with dependencies run in correct sequence
158
 */
159
orderPlugins(): void;
160
```
161

162
**Usage Examples:**
163

164
```javascript
165
// Plugin that needs to run after others
166
class CleanupPlugin extends PuppeteerExtraPlugin {
167
  constructor() {
168
    super();
169
    this.name = 'cleanup';
170
    this.requirements = new Set(['runLast']); // Runs after all other plugins
171
  }
172
}
173
```
174

175
### Plugin Lifecycle Hooks
176

177
Plugins can implement lifecycle methods that are called at specific points during browser creation and operation.
178

179
```javascript { .api }
180
/**
181
 * Plugin lifecycle methods (implemented by plugins)
182
 */
183
interface PluginLifecycle {
184
  /** Called before browser launch with options that can be modified */
185
  beforeLaunch?(options: Object): Object | Promise<Object>;
186
  
187
  /** Called after browser launch with browser instance */
188
  afterLaunch?(browser: Puppeteer.Browser, opts: { options: Object }): void | Promise<void>;
189
  
190
  /** Called before browser connect with options that can be modified */
191
  beforeConnect?(options: Object): Object | Promise<Object>;
192
  
193
  /** Called after browser connect with browser instance */
194
  afterConnect?(browser: Puppeteer.Browser, opts: { options: Object }): void | Promise<void>;
195
  
196
  /** Called when browser is available (both launch and connect) */
197
  onBrowser?(browser: Puppeteer.Browser, opts: Object): void | Promise<void>;
198
  
199
  /** Called when a target is created (pages, service workers, etc.) */
200
  onTargetCreated?(target: Puppeteer.Target): void | Promise<void>;
201
  
202
  /** Called when a page target is created (convenience method) */
203
  onPageCreated?(page: Puppeteer.Page): void | Promise<void>;
204
  
205
  /** Called when a target URL changes */
206
  onTargetChanged?(target: Puppeteer.Target): void | Promise<void>;
207
  
208
  /** Called when a target is destroyed */
209
  onTargetDestroyed?(target: Puppeteer.Target): void | Promise<void>;
210
  
211
  /** Called when browser disconnects */
212
  onDisconnected?(): void | Promise<void>;
213
  
214
  /** Called when browser process closes (launch only) */
215
  onClose?(): void | Promise<void>;
216
  
217
  /** Called after plugin registration */
218
  onPluginRegistered?(): void | Promise<void>;
219
  
220
  /** Internal method for binding browser events */
221
  _bindBrowserEvents?(browser: Puppeteer.Browser, opts: Object): void | Promise<void>;
222
}
223

224
/**
225
 * Plugin base class properties and methods
226
 */
227
interface PuppeteerExtraPluginBase {
228
  /** Plugin name (required override) */
229
  get name(): string;
230
  
231
  /** Plugin default options */
232
  get defaults(): Object;
233
  
234
  /** Plugin requirements set */
235
  get requirements(): Set<string>;
236
  
237
  /** Plugin dependencies set */
238
  get dependencies(): Set<string>;
239
  
240
  /** Plugin data array for sharing */
241
  get data(): Array<{ name: string; value: any }>;
242
  
243
  /** Access to merged options */
244
  get opts(): Object;
245
  
246
  /** Debug logger function */
247
  get debug(): Function;
248
  
249
  /** Get data from other plugins (requires 'dataFromPlugins' requirement) */
250
  getDataFromPlugins?(name?: string): Array<{ name: string; value: any }>;
251
}
252
```
253

254
**Usage Examples:**
255

256
```javascript
257
// Complete plugin example with multiple lifecycle methods
258
class ExamplePlugin extends PuppeteerExtraPlugin {
259
  constructor(opts = {}) {
260
    super(opts);
261
    this.name = 'example';
262
    this.requirements = new Set(['dataFromPlugins']);
263
  }
264
  
265
  get defaults() {
266
    return {
267
      enableLogging: true,
268
      customArgs: []
269
    };
270
  }
271
  
272
  // Modify launch options before browser starts
273
  async beforeLaunch(options) {
274
    options.args = options.args || [];
275
    options.args.push(...this.opts.customArgs);
276
    if (this.opts.enableLogging) {
277
      options.args.push('--enable-logging');
278
    }
279
    return options;
280
  }
281
  
282
  // Called after browser is launched
283
  async afterLaunch(browser, opts) {
284
    this.debug('Browser launched with options:', opts.options);
285
  }
286
  
287
  // Handle browser connection
288
  async beforeConnect(options) {
289
    this.debug('Connecting to browser:', options.browserWSEndpoint);
290
    return options;
291
  }
292
  
293
  // Called for both launch and connect
294
  async onBrowser(browser, opts) {
295
    this.debug('Browser available, context:', opts.context);
296
  }
297
  
298
  // Handle page creation
299
  async onPageCreated(page) {
300
    if (this.opts.enableLogging) {
301
      this.debug('New page created:', await page.url());
302
    }
303
    
304
    // Example: Set custom user agent
305
    const ua = await page.browser().userAgent();
306
    await page.setUserAgent(ua.replace('HeadlessChrome/', 'Chrome/'));
307
  }
308
  
309
  // Handle target events
310
  async onTargetCreated(target) {
311
    this.debug('Target created:', target.type(), target.url());
312
  }
313
  
314
  async onTargetDestroyed(target) {
315
    this.debug('Target destroyed:', target.type(), target.url());
316
  }
317
  
318
  // Handle disconnection
319
  async onDisconnected() {
320
    this.debug('Browser disconnected');
321
  }
322
  
323
  // Plugin registration callback
324
  async onPluginRegistered() {
325
    this.debug('Plugin registered successfully');
326
    
327
    // Access data from other plugins if needed
328
    if (this.getDataFromPlugins) {
329
      const pluginData = this.getDataFromPlugins('stealth');
330
      this.debug('Stealth plugin data:', pluginData);
331
    }
332
  }
333
}
334

335
// Usage
336
const plugin = new ExamplePlugin({
337
  enableLogging: true,
338
  customArgs: ['--disable-blink-features=AutomationControlled']
339
});
340

341
puppeteer.use(plugin);
342
```