0
# Polyfill Detection
1

2
Advanced polyfill detection and management system for automatic browser compatibility polyfills.
3

4
## Capabilities
5

6
### Detect Polyfills Function
7

8
Analyzes JavaScript/TypeScript code to automatically detect required polyfills based on browser targets.
9

10
```typescript { .api }
11
/**
12
 * Analyzes code to detect required polyfills using Babel preset-env
13
 * @param code - JavaScript/TypeScript code to analyze for polyfill requirements
14
 * @param targets - Browser targets (browserslist format) for polyfill detection
15
 * @param assumptions - Babel assumptions for code analysis optimization
16
 * @param list - Set to populate with discovered polyfill import paths
17
 * @returns Promise that resolves when polyfill detection is complete
18
 */
19
function detectPolyfills(
20
  code: string,
21
  targets: any,
22
  assumptions: Record<string, boolean>,
23
  list: Set<string>
24
): Promise<void>;
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
import { detectPolyfills } from '@vitejs/plugin-legacy';
31

32
// Detect polyfills for specific code
33
const polyfills = new Set<string>();
34
await detectPolyfills(
35
  `
36
    const promise = Promise.resolve();
37
    const array = [1, 2, 3].includes(2);
38
    const map = new Map();
39
  `,
40
  ['> 1%', 'last 2 versions'],
41
  {},
42
  polyfills
43
);
44

45
console.log(polyfills);
46
// Set containing core-js imports like:
47
// 'core-js/modules/es.promise.js'
48
// 'core-js/modules/es.array.includes.js'
49
// 'core-js/modules/es.map.js'
50
```
51

52
### Polyfill Specification Formats
53

54
Different formats for specifying polyfills in plugin configuration.
55

56
```typescript { .api }
57
type PolyfillSpecifier = string;
58

59
/**
60
 * Polyfill specifiers can be:
61
 * - core-js sub-import paths: 'es/map' -> 'core-js/es/map'
62
 * - Individual core-js modules: 'es.array.iterator' -> 'core-js/modules/es.array.iterator.js'
63
 * - Direct module paths: 'regenerator-runtime/runtime'
64
 */
65
```
66

67
**Examples:**
68

69
```typescript
70
legacy({
71
  // Different polyfill specification formats
72
  polyfills: [
73
    'es.promise.finally',        // Individual module
74
    'es/map',                    // Sub-import path
75
    'es/set',                    // Sub-import path
76
    'regenerator',               // Special case for regenerator-runtime
77
  ],
78
  
79
  additionalLegacyPolyfills: [
80
    'intersection-observer',     // Third-party polyfill
81
    'custom-polyfill',          // Custom polyfill
82
  ],
83
  
84
  modernPolyfills: [
85
    'es.promise.finally',        // Only newer features for modern builds
86
  ],
87
});
88
```
89

90
### Automatic Polyfill Detection
91

92
Configuration options for automatic polyfill detection behavior.
93

94
```typescript { .api }
95
interface AutomaticPolyfillOptions {
96
  /** Enable automatic polyfill detection based on code usage */
97
  polyfills: true;
98
  
99
  /** Browser targets for polyfill requirement analysis */
100
  targets?: string | string[] | Record<string, string>;
101
  
102
  /** Modern browser targets for modern polyfill detection */
103
  modernTargets?: string | string[];
104
  
105
  /** Enable modern polyfill detection (requires modernTargets or uses defaults) */
106
  modernPolyfills?: boolean;
107
}
108
```
109

110
**Usage Examples:**
111

112
```typescript
113
// Full automatic detection
114
legacy({
115
  polyfills: true,
116
  modernPolyfills: true,
117
  targets: ['> 0.5%', 'last 2 versions'],
118
  modernTargets: ['supports es6-module'],
119
});
120

121
// Legacy-only automatic detection
122
legacy({
123
  polyfills: true,
124
  modernPolyfills: false,
125
  targets: ['IE 11', 'Chrome >= 49'],
126
});
127
```
128

129
### Manual Polyfill Configuration
130

131
Explicit polyfill specification for fine-grained control.
132

133
```typescript { .api }
134
interface ManualPolyfillOptions {
135
  /** Specific polyfills to include (disables automatic detection) */
136
  polyfills: string[];
137
  
138
  /** Additional polyfills beyond automatic detection */
139
  additionalLegacyPolyfills?: string[];
140
  
141
  /** Additional modern polyfills beyond automatic detection */
142
  additionalModernPolyfills?: string[];
143
  
144
  /** Specific modern polyfills (disables automatic modern detection) */
145
  modernPolyfills?: string[];
146
}
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
// Completely manual polyfill control
153
legacy({
154
  polyfills: [
155
    'core-js/modules/es.promise.js',
156
    'core-js/modules/es.array.includes.js',
157
    'regenerator-runtime/runtime.js',
158
  ],
159
  modernPolyfills: [
160
    'core-js/modules/es.promise.finally.js',
161
  ],
162
});
163

164
// Hybrid approach: automatic + additional
165
legacy({
166
  polyfills: true,  // Automatic detection
167
  additionalLegacyPolyfills: [
168
    'intersection-observer',
169
    'resize-observer-polyfill',
170
  ],
171
  additionalModernPolyfills: [
172
    'core-js/proposals/global-this',
173
  ],
174
});
175
```
176

177
### Disabling Polyfills
178

179
Options to disable polyfill generation entirely.
180

181
```typescript { .api }
182
interface DisabledPolyfillOptions {
183
  /** Disable all polyfill generation */
184
  polyfills: false;
185
  
186
  /** Modern polyfills still configurable when legacy polyfills disabled */
187
  modernPolyfills?: boolean | string[];
188
}
189
```
190

191
**Usage Examples:**
192

193
```typescript
194
// No polyfills (syntax transformation only)
195
legacy({
196
  polyfills: false,
197
  targets: ['> 1%', 'last 2 versions'],
198
});
199

200
// Legacy disabled, modern enabled
201
legacy({
202
  polyfills: false,
203
  modernPolyfills: ['es.promise.finally'],
204
  renderLegacyChunks: false,
205
});
206
```
207

208
## Core-js Integration
209

210
The plugin integrates with core-js for comprehensive polyfill coverage.
211

212
```typescript { .api }
213
/**
214
 * Supported polyfill import patterns:
215
 * - 'es/promise' -> 'core-js/es/promise'
216
 * - 'es.promise.finally' -> 'core-js/modules/es.promise.finally.js'
217
 * - 'regenerator' -> 'regenerator-runtime/runtime.js'
218
 */
219
type CoreJSPolyfillPath = string;
220
```
221

222
**Common Core-js Polyfills:**
223

224
```typescript
225
legacy({
226
  polyfills: [
227
    // ES6+ Features
228
    'es.promise',
229
    'es.promise.finally',
230
    'es.array.includes',
231
    'es.array.find',
232
    'es.array.flat',
233
    'es.object.assign',
234
    'es.string.includes',
235
    
236
    // Collections
237
    'es.map',
238
    'es.set',
239
    'es.weak-map',
240
    'es.weak-set',
241
    
242
    // Async/Iterator support
243
    'regenerator',
244
    'es.symbol.async-iterator',
245
    
246
    // Newer proposals
247
    'es.string.replace-all',
248
    'es.promise.all-settled',
249
  ],
250
});
251
```