0
# Playwright Extra
1

2
Playwright Extra is a modular plugin framework for Playwright that extends browser automation capabilities through a clean plugin interface. It serves as a drop-in replacement for the standard Playwright library, adding plugin functionality while maintaining full compatibility with Playwright's API. The framework supports multiple browsers (Chromium, Firefox, WebKit) and enables easy integration of various automation enhancements such as stealth mode, CAPTCHA solving, and other browser automation tricks.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { chromium, firefox, webkit, addExtra } from "playwright-extra";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { chromium, firefox, webkit, addExtra } = require("playwright-extra");
21
```
22

23
Re-exported Playwright modules:
24

25
```typescript
26
import { devices, errors, selectors, request, _android, _electron } from "playwright-extra";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { chromium } from "playwright-extra";
33
import StealthPlugin from "puppeteer-extra-plugin-stealth";
34

35
// Add plugins to the browser launcher
36
chromium.use(StealthPlugin());
37

38
// Use exactly like standard Playwright
39
const browser = await chromium.launch({ headless: true });
40
const page = await browser.newPage();
41

42
await page.goto("https://example.com");
43
await page.screenshot({ path: "screenshot.png" });
44
await browser.close();
45
```
46

47
## Architecture
48

49
Playwright Extra is built around several key components:
50

51
- **Browser Launchers**: Enhanced versions of Playwright's `chromium`, `firefox`, and `webkit` with plugin functionality
52
- **Plugin System**: Framework for registering and managing plugins that extend browser capabilities
53
- **Compatibility Layer**: Shim that enables puppeteer-extra plugins to work with Playwright
54
- **Lifecycle Hooks**: Event system that allows plugins to intercept and modify browser operations
55
- **Lazy Loading**: Dynamic module loading system for re-exported Playwright functionality
56

57
## Capabilities
58

59
### Enhanced Browser Launchers
60

61
Enhanced browser launchers that provide the same API as standard Playwright with additional plugin functionality. Each launcher supports plugin registration and manages plugin lifecycle events.
62

63
```typescript { .api }
64
const chromium: AugmentedBrowserLauncher;
65
const firefox: AugmentedBrowserLauncher;
66
const webkit: AugmentedBrowserLauncher;
67

68
interface AugmentedBrowserLauncher extends PlaywrightBrowserLauncher {
69
  use(plugin: CompatiblePlugin): this;
70
  plugins: PluginList;
71
}
72
```
73

74
[Browser Launchers](./browser-launchers.md)
75

76
### Custom Launcher Integration
77

78
Create independent plugin-enabled instances from any compatible Playwright launcher. Useful when you need multiple instances with different plugin configurations.
79

80
```typescript { .api }
81
function addExtra<Launcher extends PlaywrightCompatibleLauncher>(
82
  launcher?: Launcher
83
): PlaywrightExtraClass & Launcher;
84

85
interface PlaywrightCompatibleLauncher {
86
  connect(...args: any[]): Promise<any>;
87
  launch(...args: any[]): Promise<any>;
88
}
89
```
90

91
[Custom Integration](./custom-integration.md)
92

93
### Plugin Management
94

95
Comprehensive plugin management system supporting plugin registration, dependency resolution, lifecycle management, and error handling.
96

97
```typescript { .api }
98
class PluginList {
99
  readonly list: Plugin[];
100
  readonly names: string[];
101
  
102
  add(plugin: Plugin): boolean;
103
  setDependencyDefaults(dependencyPath: string, opts: any): this;
104
  setDependencyResolution(dependencyPath: string, pluginModule: CompatiblePluginModule): this;
105
  onPluginError(plugin: Plugin, method: PluginMethodName, err: Error): void;
106
}
107
```
108

109
[Plugin Management](./plugin-management.md)
110

111
### Plugin Development
112

113
Interfaces and types for creating compatible plugins that work with both Playwright Extra and puppeteer-extra. Includes lifecycle methods and compatibility requirements.
114

115
```typescript { .api }
116
interface PuppeteerExtraPlugin extends Partial<PluginLifecycleMethods> {
117
  _isPuppeteerExtraPlugin: boolean;
118
  name: string;
119
  noPuppeteerShim?: boolean;
120
  requirements?: PluginRequirements;
121
  dependencies?: PluginDependencies;
122
}
123

124
abstract class PluginLifecycleMethods {
125
  async onPluginRegistered(env?: PluginEnv): Promise<void>;
126
  async beforeLaunch(options: LaunchOptions): Promise<LaunchOptions | void>;
127
  async afterLaunch(browserOrContext?: Browser | BrowserContext): Promise<void>;
128
  async beforeConnect(options: ConnectOptions): Promise<ConnectOptions | void>;
129
  async afterConnect(browser: Browser): Promise<void>;
130
  async onBrowser(browser: Browser): Promise<void>;
131
  async onPageCreated(page: Page): Promise<void>;
132
  async onPageClose(page: Page): Promise<void>;
133
  async onDisconnected(browser?: Browser): Promise<void>;
134
  async beforeContext(options?: BrowserContextOptions, browser?: Browser): Promise<BrowserContextOptions | void>;
135
  async onContextCreated(context?: BrowserContext, options?: BrowserContextOptions): Promise<void>;
136
}
137
```
138

139
[Plugin Development](./plugin-development.md)
140

141
### Puppeteer Compatibility
142

143
Compatibility layer that allows puppeteer-extra plugins to work seamlessly with Playwright by providing a shim layer that translates Playwright objects to Puppeteer-compatible interfaces.
144

145
```typescript { .api }
146
function addPuppeteerCompat<Input extends Page | Frame | Browser | null>(
147
  object: Input
148
): Input;
149

150
interface PuppeteerBrowserShim {
151
  isCompatShim?: boolean;
152
  isPlaywright?: boolean;
153
  pages?: BrowserContext['pages'];
154
  userAgent(): Promise<string>;
155
}
156

157
interface PuppeteerPageShim {
158
  isCompatShim?: boolean;
159
  isPlaywright?: boolean;
160
  browser?(): Browser;
161
  evaluateOnNewDocument?: Page['addInitScript'];
162
  _client(): CDPSession;
163
}
164
```
165

166
[Puppeteer Compatibility](./puppeteer-compatibility.md)
167

168
## Core Types
169

170
```typescript { .api }
171
type CompatiblePlugin = 
172
  | CompatiblePuppeteerPlugin 
173
  | CompatiblePlaywrightPlugin 
174
  | CompatibleExtraPlugin;
175

176
type PluginMethodName = keyof PluginLifecycleMethods;
177

178
type PluginRequirements = Set<'launch' | 'headful' | 'dataFromPlugins' | 'runLast'>;
179

180
type PluginDependencies = Set<string> | Map<string, any> | string[];
181

182
interface PluginEnv {
183
  framework: 'playwright';
184
}
185
```
186

187
## Re-exported Playwright APIs
188

189
Playwright Extra re-exports all standard Playwright APIs with lazy loading:
190

191
```typescript { .api }
192
/** Standard Playwright device descriptors */
193
const devices: typeof import('playwright-core').devices;
194

195
/** Playwright error classes */
196
const errors: typeof import('playwright-core').errors;
197

198
/** Playwright selectors engine */
199
const selectors: typeof import('playwright-core').selectors;
200

201
/** Playwright request API */
202
const request: typeof import('playwright-core').request;
203

204
/** Android device support (lazy-loaded) */
205
const _android: typeof import('playwright-core')._android;
206

207
/** Electron app support (lazy-loaded) */
208
const _electron: typeof import('playwright-core')._electron;
209
```