0
# Core Plugin Management
1

2
Core plugin functionality for configuring and managing stealth evasions. The main StealthPlugin class controls which evasion techniques are active and provides access to plugin metadata.
3

4
## Capabilities
5

6
### StealthPlugin Factory Function
7

8
Creates a new stealth plugin instance with optional configuration.
9

10
```javascript { .api }
11
/**
12
 * Creates a new stealth plugin instance
13
 * @param opts - Configuration options
14
 * @param opts.enabledEvasions - Set of evasion names to enable (default: all available)
15
 * @returns StealthPlugin instance ready to use with puppeteer-extra
16
 */
17
function StealthPlugin(opts?: {
18
  enabledEvasions?: Set<string>;
19
}): StealthPlugin;
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
26

27
// Enable all evasions (default behavior)
28
const stealthPlugin = StealthPlugin();
29

30
// Enable only specific evasions
31
const customStealth = StealthPlugin({
32
  enabledEvasions: new Set([
33
    'navigator.webdriver',
34
    'user-agent-override',
35
    'chrome.runtime'
36
  ])
37
});
38

39
// Use with puppeteer-extra
40
const puppeteer = require('puppeteer-extra');
41
puppeteer.use(stealthPlugin);
42
```
43

44
### StealthPlugin Class
45

46
Main plugin class that extends PuppeteerExtraPlugin and manages stealth evasion techniques.
47

48
```javascript { .api }
49
class StealthPlugin extends PuppeteerExtraPlugin {
50
  /**
51
   * Constructor for StealthPlugin
52
   * @param opts - Configuration options object
53
   */
54
  constructor(opts?: Record<string, any>);
55
}
56
```
57

58
### Plugin Name
59

60
Unique identifier for the stealth plugin.
61

62
```javascript { .api }
63
/**
64
 * Plugin identifier name
65
 * @returns Always returns 'stealth'
66
 */
67
get name(): string;
68
```
69

70
### Default Configuration
71

72
Default configuration including all available evasion techniques.
73

74
```javascript { .api }
75
/**
76
 * Default plugin configuration
77
 * @returns Object containing available and enabled evasions
78
 */
79
get defaults(): {
80
  availableEvasions: Set<string>;
81
  enabledEvasions: Set<string>;
82
};
83
```
84

85
### Available Evasions
86

87
Get all available evasion technique names.
88

89
```javascript { .api }
90
/**
91
 * Get all available evasion techniques
92
 * @returns Set of all available evasion technique names
93
 */
94
get availableEvasions(): Set<string>;
95
```
96

97
The available evasions include:
98
- `chrome.app`
99
- `chrome.csi`
100
- `chrome.loadTimes`
101
- `chrome.runtime`
102
- `defaultArgs`
103
- `iframe.contentWindow`
104
- `media.codecs`
105
- `navigator.hardwareConcurrency`
106
- `navigator.languages`
107
- `navigator.permissions`
108
- `navigator.plugins`
109
- `navigator.webdriver`
110
- `sourceurl`
111
- `user-agent-override`
112
- `webgl.vendor`
113
- `window.outerdimensions`
114

115
### Enabled Evasions Management
116

117
Get or set which evasion techniques are currently enabled.
118

119
```javascript { .api }
120
/**
121
 * Get currently enabled evasion techniques
122
 * @returns Set of enabled evasion technique names
123
 */
124
get enabledEvasions(): Set<string>;
125

126
/**
127
 * Set which evasion techniques should be enabled
128
 * @param evasions - Set of evasion technique names to enable
129
 */
130
set enabledEvasions(evasions: Set<string>): void;
131
```
132

133
**Usage Examples:**
134

135
```javascript
136
const stealth = StealthPlugin();
137

138
// View enabled evasions
139
console.log(stealth.enabledEvasions);
140
// Set { 'chrome.app', 'chrome.csi', ... all evasions }
141

142
// Remove specific evasion
143
stealth.enabledEvasions.delete('navigator.plugins');
144

145
// Add specific evasion back
146
stealth.enabledEvasions.add('navigator.plugins');
147

148
// Replace with custom set
149
stealth.enabledEvasions = new Set([
150
  'navigator.webdriver',
151
  'user-agent-override'
152
]);
153
```
154

155
### Browser Setup Hook
156

157
Browser-level configuration hook that executes when a browser instance is created.
158

159
```javascript { .api }
160
/**
161
 * Browser setup hook for configuring browser-level options
162
 * @param browser - Browser instance from puppeteer
163
 * @returns Promise that resolves when setup is complete
164
 */
165
onBrowser(browser: any): Promise<void>;
166
```
167

168
This method:
169
- Sets the maximum number of event listeners to 30 to prevent warnings
170
- Is called automatically by the puppeteer-extra plugin system
171
- Should not be called manually by users
172

173
### Plugin Dependencies
174

175
Internal system for managing dynamic plugin dependencies based on enabled evasions.
176

177
```javascript { .api }
178
/**
179
 * Internal dependency management (private)
180
 * @returns Set of plugin dependency paths
181
 */
182
get dependencies(): Set<string>;
183
```
184

185
This property:
186
- Automatically generates dependency paths for enabled evasions
187
- Is used internally by the puppeteer-extra plugin system
188
- Should not be accessed directly by users
189
- Returns paths in format: `stealth/evasions/${evasionName}`
190

191
## Configuration Patterns
192

193
### Selective Evasion Usage
194

195
```javascript
196
// Enable only navigator-related evasions
197
const navigatorStealth = StealthPlugin({
198
  enabledEvasions: new Set([
199
    'navigator.webdriver',
200
    'navigator.languages',
201
    'navigator.plugins',
202
    'navigator.hardwareConcurrency',
203
    'navigator.permissions'
204
  ])
205
});
206

207
// Enable only Chrome API evasions
208
const chromeStealth = StealthPlugin({
209
  enabledEvasions: new Set([
210
    'chrome.app',
211
    'chrome.csi',
212
    'chrome.loadTimes',
213
    'chrome.runtime'
214
  ])
215
});
216
```
217

218
### Dynamic Evasion Management
219

220
```javascript
221
const stealth = StealthPlugin();
222

223
// Start with all evasions, then remove problematic ones
224
stealth.enabledEvasions.delete('chrome.runtime');
225
stealth.enabledEvasions.delete('navigator.plugins');
226

227
// Or start minimal and add as needed
228
const minimal = StealthPlugin({
229
  enabledEvasions: new Set(['navigator.webdriver'])
230
});
231

232
// Add more evasions later
233
minimal.enabledEvasions.add('user-agent-override');
234
minimal.enabledEvasions.add('window.outerdimensions');
235
```