0
# Browser Launchers
1

2
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 throughout the browser's lifecycle.
3

4
## Capabilities
5

6
### Chromium Launcher
7

8
Chromium browser launcher with plugin functionality. This is the default export that automatically loads the installed playwright or playwright-core module.
9

10
```typescript { .api }
11
const chromium: AugmentedBrowserLauncher;
12
```
13

14
**Usage Examples:**
15

16
```typescript
17
import { chromium } from "playwright-extra";
18
import StealthPlugin from "puppeteer-extra-plugin-stealth";
19

20
// Add plugins
21
chromium.use(StealthPlugin());
22

23
// Launch browser (same as standard Playwright)
24
const browser = await chromium.launch({
25
  headless: true,
26
  args: ['--no-sandbox']
27
});
28

29
const context = await browser.newContext();
30
const page = await context.newPage();
31
```
32

33
### Firefox Launcher
34

35
Firefox browser launcher with plugin functionality.
36

37
```typescript { .api }
38
const firefox: AugmentedBrowserLauncher;
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
import { firefox } from "playwright-extra";
45
import RecaptchaPlugin from "puppeteer-extra-plugin-recaptcha";
46

47
// Add plugins
48
firefox.use(RecaptchaPlugin({
49
  provider: {
50
    id: '2captcha',
51
    token: 'YOUR_API_KEY'
52
  }
53
}));
54

55
// Launch Firefox
56
const browser = await firefox.launch({ headless: false });
57
```
58

59
### WebKit Launcher
60

61
WebKit browser launcher with plugin functionality.
62

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

67
**Usage Examples:**
68

69
```typescript
70
import { webkit } from "playwright-extra";
71

72
// Add plugins
73
webkit.use(plugin);
74

75
// Launch WebKit
76
const browser = await webkit.launch({ headless: true });
77
```
78

79
### Launch Method
80

81
Launch a browser instance with plugin support. All plugins are executed before and after the launch process.
82

83
```typescript { .api }
84
async launch(
85
  options?: LaunchOptions
86
): Promise<Browser>;
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import { chromium } from "playwright-extra";
93

94
// Launch with options
95
const browser = await chromium.launch({
96
  headless: true,
97
  slowMo: 50,
98
  args: ['--disable-web-security']
99
});
100

101
// Plugins can modify launch options via beforeLaunch hook
102
```
103

104
### Launch Persistent Context Method
105

106
Launch a browser with a persistent context. This method combines browser launching and context creation into one step.
107

108
```typescript { .api }
109
async launchPersistentContext(
110
  userDataDir: string,
111
  options?: BrowserContextOptions & LaunchOptions
112
): Promise<BrowserContext>;
113
```
114

115
**Usage Examples:**
116

117
```typescript
118
import { chromium } from "playwright-extra";
119

120
// Launch with persistent context
121
const context = await chromium.launchPersistentContext('./user-data', {
122
  headless: false,
123
  viewport: { width: 1280, height: 720 }
124
});
125

126
const page = await context.newPage();
127
```
128

129
### Connect Method
130

131
Connect to an existing browser instance via WebSocket endpoint with plugin support.
132

133
```typescript { .api }
134
async connect(
135
  wsEndpointOrOptions: string | (ConnectOptions & { wsEndpoint?: string }),
136
  wsOptions?: ConnectOptions
137
): Promise<Browser>;
138
```
139

140
**Usage Examples:**
141

142
```typescript
143
import { chromium } from "playwright-extra";
144

145
// Connect using WebSocket endpoint string
146
const browser = await chromium.connect('ws://localhost:9222/devtools/browser');
147

148
// Connect with additional options
149
const browser = await chromium.connect('ws://localhost:9222/devtools/browser', {
150
  timeout: 30000
151
});
152

153
// Connect using options object
154
const browser = await chromium.connect({
155
  wsEndpoint: 'ws://localhost:9222/devtools/browser',
156
  timeout: 30000
157
});
158
```
159

160
### Connect Over CDP Method
161

162
Connect to an existing Chromium browser via Chrome DevTools Protocol.
163

164
```typescript { .api }
165
async connectOverCDP(
166
  wsEndpointOrOptions: string | (ConnectOverCDPOptions & { endpointURL?: string }),
167
  wsOptions?: ConnectOverCDPOptions
168
): Promise<Browser>;
169
```
170

171
**Usage Examples:**
172

173
```typescript
174
import { chromium } from "playwright-extra";
175

176
// Connect over CDP using endpoint URL string
177
const browser = await chromium.connectOverCDP('http://localhost:9222');
178

179
// Connect with additional options
180
const browser = await chromium.connectOverCDP('http://localhost:9222', {
181
  timeout: 10000
182
});
183

184
// Connect using options object
185
const browser = await chromium.connectOverCDP({
186
  endpointURL: 'http://localhost:9222',
187
  timeout: 10000
188
});
189
```
190

191
### Plugin Registration
192

193
Register a plugin with the browser launcher. Plugins are registered globally for the launcher instance.
194

195
```typescript { .api }
196
use(plugin: CompatiblePlugin): this;
197
```
198

199
**Usage Examples:**
200

201
```typescript
202
import { chromium } from "playwright-extra";
203
import StealthPlugin from "puppeteer-extra-plugin-stealth";
204
import RecaptchaPlugin from "puppeteer-extra-plugin-recaptcha";
205

206
// Chain multiple plugins
207
chromium
208
  .use(StealthPlugin())
209
  .use(RecaptchaPlugin({ 
210
    provider: { id: '2captcha', token: 'key' } 
211
  }));
212

213
// Individual plugin registration
214
chromium.use(StealthPlugin());
215
chromium.use(RecaptchaPlugin());
216
```
217

218
### Plugin Manager Access
219

220
Access the plugin manager for advanced plugin configuration and inspection.
221

222
```typescript { .api }
223
readonly plugins: PluginList;
224
```
225

226
**Usage Examples:**
227

228
```typescript
229
import { chromium } from "playwright-extra";
230

231
// Access plugin list
232
console.log(chromium.plugins.names); // ['stealth', 'recaptcha']
233

234
// Set dependency defaults
235
chromium.plugins.setDependencyDefaults('stealth/evasions/webgl.vendor', {
236
  vendor: 'Custom Vendor',
237
  renderer: 'Custom Renderer'
238
});
239

240
// Get plugin instances
241
const pluginList = chromium.plugins.list;
242
```
243

244
## Core Types
245

246
```typescript { .api }
247
interface AugmentedBrowserLauncher extends PlaywrightBrowserLauncher {
248
  use(plugin: CompatiblePlugin): this;
249
  plugins: PluginList;
250
}
251

252
type PlaywrightBrowserLauncher = BrowserType<{}>;
253

254
interface LaunchOptions {
255
  headless?: boolean;
256
  args?: string[];
257
  ignoreDefaultArgs?: boolean | string[];
258
  proxy?: {
259
    server: string;
260
    bypass?: string;
261
    username?: string;
262
    password?: string;
263
  };
264
  downloadsPath?: string;
265
  chromiumSandbox?: boolean;
266
  firefoxUserPrefs?: { [key: string]: string | number | boolean };
267
  slowMo?: number;
268
  timeout?: number;
269
}
270

271
interface ConnectOptions {
272
  wsEndpoint?: string;
273
  timeout?: number;
274
  slowMo?: number;
275
}
276

277
interface ConnectOverCDPOptions {
278
  endpointURL?: string;
279
  timeout?: number;
280
  slowMo?: number;
281
}
282
```