0
# Custom Launcher Integration
1

2
Create independent plugin-enabled instances from any compatible Playwright launcher. This is useful when you need multiple instances with different plugin configurations or when working with custom or non-standard Playwright implementations.
3

4
## Capabilities
5

6
### Add Extra Function
7

8
Augment any compatible Playwright browser launcher with plugin functionality. This creates a fresh PlaywrightExtra instance, unlike the default exports which return cached instances.
9

10
```typescript { .api }
11
/**
12
 * Augment the provided Playwright browser launcher with plugin functionality.
13
 * Using addExtra will always create a fresh PlaywrightExtra instance.
14
 * @param launcher - Playwright (or compatible) browser launcher
15
 * @returns Enhanced launcher with plugin functionality
16
 */
17
function addExtra<Launcher extends PlaywrightCompatibleLauncher>(
18
  launcher?: Launcher
19
): PlaywrightExtraClass & Launcher;
20
```
21

22
**Usage Examples:**
23

24
```typescript
25
import playwright from "playwright";
26
import { addExtra } from "playwright-extra";
27

28
// Create independent instances
29
const chromium1 = addExtra(playwright.chromium);
30
const chromium2 = addExtra(playwright.chromium);
31

32
// Each instance can have different plugins
33
chromium1.use(pluginA);
34
chromium2.use(pluginB);
35

36
// Instances are completely independent
37
const browser1 = await chromium1.launch();
38
const browser2 = await chromium2.launch();
39
```
40

41
### Multiple Instance Pattern
42

43
Create multiple independent instances with different plugin configurations.
44

45
```typescript
46
import playwright from "playwright";
47
import { addExtra } from "playwright-extra";
48
import StealthPlugin from "puppeteer-extra-plugin-stealth";
49
import RecaptchaPlugin from "puppeteer-extra-plugin-recaptcha";
50

51
// Create specialized instances
52
const stealthChromium = addExtra(playwright.chromium);
53
stealthChromium.use(StealthPlugin());
54

55
const captchaChromium = addExtra(playwright.chromium);
56
captchaChromium.use(RecaptchaPlugin({
57
  provider: { id: '2captcha', token: 'key' }
58
}));
59

60
// Use instances independently
61
const stealthBrowser = await stealthChromium.launch({ headless: true });
62
const captchaBrowser = await captchaChromium.launch({ headless: false });
63
```
64

65
### Custom Launcher Integration
66

67
Integrate with custom or non-standard Playwright implementations.
68

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

72
// Custom launcher that implements the required interface
73
const customLauncher = {
74
  async launch(options) {
75
    // Custom launch implementation
76
    return customBrowser;
77
  },
78
  async connect(wsEndpoint, options) {
79
    // Custom connect implementation
80
    return customBrowser;
81
  }
82
};
83

84
// Enhance custom launcher with plugins
85
const enhancedLauncher = addExtra(customLauncher);
86
enhancedLauncher.use(plugin);
87

88
const browser = await enhancedLauncher.launch();
89
```
90

91
### Without Launcher Parameter
92

93
Create a fresh instance without specifying a launcher. The instance will attempt to load Playwright when methods are called.
94

95
```typescript
96
import { addExtra } from "playwright-extra";
97

98
// Create instance without launcher
99
const launcher = addExtra();
100
launcher.use(plugin);
101

102
// Will attempt to load playwright-core or playwright when launch is called
103
const browser = await launcher.launch();
104
```
105

106
## PlaywrightExtra Class
107

108
The core class that implements plugin functionality for Playwright launchers.
109

110
### Constructor
111

112
```typescript { .api }
113
constructor(launcher?: Partial<PlaywrightBrowserLauncher>);
114
```
115

116
Create a new PlaywrightExtra instance with an optional launcher.
117

118
### Plugin Registration
119

120
```typescript { .api }
121
/**
122
 * The main interface to register plugins.
123
 * Can be called multiple times to enable multiple plugins.
124
 * @param plugin - Plugin instance to register
125
 * @returns The same PlaywrightExtra instance for optional chaining
126
 */
127
use(plugin: CompatiblePlugin): this;
128
```
129

130
### Plugin Manager
131

132
```typescript { .api }
133
readonly plugins: PluginList;
134
```
135

136
Access to the plugin manager for advanced configuration.
137

138
### Browser Operations
139

140
The class implements all standard Playwright browser launcher methods with plugin support:
141

142
```typescript { .api }
143
async launch(
144
  options?: LaunchOptions
145
): Promise<Browser>;
146

147
async launchPersistentContext(
148
  userDataDir: string,
149
  options?: BrowserContextOptions & LaunchOptions
150
): Promise<BrowserContext>;
151

152
async connect(
153
  wsEndpointOrOptions: string | (ConnectOptions & { wsEndpoint?: string }),
154
  wsOptions?: ConnectOptions
155
): Promise<Browser>;
156

157
async connectOverCDP(
158
  wsEndpointOrOptions: string | (ConnectOverCDPOptions & { endpointURL?: string }),
159
  wsOptions?: ConnectOverCDPOptions
160
): Promise<Browser>;
161
```
162

163
## Core Types
164

165
```typescript { .api }
166
interface PlaywrightCompatibleLauncher {
167
  connect(...args: any[]): Promise<any>;
168
  launch(...args: any[]): Promise<any>;
169
}
170

171
class PlaywrightExtraClass {
172
  readonly plugins: PluginList;
173
  
174
  constructor(launcher?: Partial<PlaywrightBrowserLauncher>);
175
  use(plugin: CompatiblePlugin): this;
176
  
177
  async launch(options?: LaunchOptions): Promise<Browser>;
178
  async launchPersistentContext(userDataDir: string, options?: BrowserContextOptions & LaunchOptions): Promise<BrowserContext>;
179
  async connect(wsEndpointOrOptions: string | ConnectOptions, wsOptions?: ConnectOptions): Promise<Browser>;
180
  async connectOverCDP(wsEndpointOrOptions: string | ConnectOverCDPOptions, wsOptions?: ConnectOverCDPOptions): Promise<Browser>;
181
}
182

183
type PlaywrightBrowserLauncher = BrowserType<{}>;
184
```