0
# Plugin Configuration
1

2
Comprehensive configuration options for @vitejs/plugin-legacy to customize legacy browser support behavior.
3

4
## Capabilities
5

6
### Main Plugin Function
7

8
The primary plugin factory function that creates the complete legacy browser support system.
9

10
```typescript { .api }
11
/**
12
 * Creates legacy browser support plugins for Vite
13
 * @param options - Configuration options for legacy support
14
 * @returns Array of three plugins: config, generate-bundle, and post-process
15
 */
16
function viteLegacyPlugin(options?: Options): Plugin[];
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { defineConfig } from 'vite';
23
import legacy from '@vitejs/plugin-legacy';
24

25
// Basic usage with default settings
26
export default defineConfig({
27
  plugins: [
28
    legacy(),
29
  ],
30
});
31

32
// Custom browser targets
33
export default defineConfig({
34
  plugins: [
35
    legacy({
36
      targets: ['> 1%', 'last 2 versions', 'not dead'],
37
      modernTargets: ['chrome >= 64', 'firefox >= 67', 'safari >= 12'],
38
    }),
39
  ],
40
});
41

42
// Custom polyfills
43
export default defineConfig({
44
  plugins: [
45
    legacy({
46
      targets: ['IE 11'],
47
      polyfills: ['es.promise', 'es.array.includes'],
48
      additionalLegacyPolyfills: ['custom-polyfill'],
49
    }),
50
  ],
51
});
52
```
53

54
### Browser Targets Configuration
55

56
Configure which browsers to support for legacy and modern builds.
57

58
```typescript { .api }
59
interface TargetsOptions {
60
  /** 
61
   * Browser targets for legacy builds using browserslist syntax
62
   * @default 'last 2 versions and not dead, > 0.3%, Firefox ESR'
63
   */
64
  targets?: string | string[] | Record<string, string>;
65
  
66
  /** 
67
   * Browser targets for modern builds using browserslist syntax
68
   * @default 'edge>=79, firefox>=67, chrome>=64, safari>=12, chromeAndroid>=64, iOS>=12'
69
   */
70
  modernTargets?: string | string[];
71
}
72
```
73

74
**Examples:**
75

76
```typescript
77
// String format
78
legacy({
79
  targets: 'last 2 versions and not dead',
80
  modernTargets: 'supports es6-module',
81
});
82

83
// Array format
84
legacy({
85
  targets: ['> 1%', 'last 2 versions', 'not IE 11'],
86
  modernTargets: ['chrome >= 64', 'firefox >= 67'],
87
});
88

89
// Object format (for specific versions)
90
legacy({
91
  targets: {
92
    chrome: '58',
93
    firefox: '57',
94
    safari: '11',
95
    edge: '16',
96
  },
97
});
98
```
99

100
### Polyfill Configuration
101

102
Control which polyfills are included in legacy and modern builds.
103

104
```typescript { .api }
105
interface PolyfillOptions {
106
  /** 
107
   * Enable automatic polyfill detection or specify custom polyfills
108
   * @default true
109
   */
110
  polyfills?: boolean | string[];
111
  
112
  /** Additional polyfills for legacy builds */
113
  additionalLegacyPolyfills?: string[];
114
  
115
  /** Additional polyfills for modern builds */
116
  additionalModernPolyfills?: string[];
117
  
118
  /** 
119
   * Modern polyfill configuration for ESM-capable browsers
120
   * @default false
121
   */
122
  modernPolyfills?: boolean | string[];
123
}
124
```
125

126
**Examples:**
127

128
```typescript
129
// Automatic polyfill detection (default)
130
legacy({
131
  polyfills: true,
132
});
133

134
// Disable polyfills entirely
135
legacy({
136
  polyfills: false,
137
});
138

139
// Custom polyfill list
140
legacy({
141
  polyfills: ['es.promise.finally', 'es.array.flat'],
142
  additionalLegacyPolyfills: ['intersection-observer'],
143
  modernPolyfills: ['es.promise.finally'],
144
});
145
```
146

147
### Build Control Options
148

149
Control which types of bundles are generated.
150

151
```typescript { .api }
152
interface BuildOptions {
153
  /** 
154
   * Generate legacy SystemJS chunks
155
   * @default true
156
   */
157
  renderLegacyChunks?: boolean;
158
  
159
  /** 
160
   * Generate modern ESM chunks
161
   * @default true
162
   */
163
  renderModernChunks?: boolean;
164
  
165
  /** 
166
   * Exclude SystemJS runtime from polyfill chunk
167
   * @default false
168
   */
169
  externalSystemJS?: boolean;
170
}
171
```
172

173
**Examples:**
174

175
```typescript
176
// Modern polyfills only (no legacy chunks)
177
legacy({
178
  renderLegacyChunks: false,
179
  modernPolyfills: ['es.promise.finally'],
180
});
181

182
// Legacy only (for file:// protocol compatibility)
183
legacy({
184
  renderModernChunks: false,
185
  targets: ['> 0.5%', 'last 2 versions'],
186
});
187

188
// External SystemJS (reduce bundle size)
189
legacy({
190
  externalSystemJS: true,
191
});
192
```
193

194
### Advanced Configuration
195

196
Advanced options for fine-tuning Babel transformation behavior.
197

198
```typescript { .api }
199
interface AdvancedOptions {
200
  /** 
201
   * Babel assumptions for code transformation optimization
202
   * @see https://babeljs.io/docs/assumptions
203
   * @default {}
204
   */
205
  assumptions?: Record<string, boolean>;
206
}
207
```
208

209
**Examples:**
210

211
```typescript
212
// Babel assumptions for smaller output
213
legacy({
214
  assumptions: {
215
    setPublicClassFields: true,
216
    privateFieldsAsProperties: true,
217
  },
218
});
219
```
220

221
## Complete Options Interface
222

223
```typescript { .api }
224
interface Options {
225
  targets?: string | string[] | Record<string, string>;
226
  modernTargets?: string | string[];
227
  polyfills?: boolean | string[];
228
  additionalLegacyPolyfills?: string[];
229
  additionalModernPolyfills?: string[];
230
  modernPolyfills?: boolean | string[];
231
  renderLegacyChunks?: boolean;
232
  externalSystemJS?: boolean;
233
  renderModernChunks?: boolean;
234
  assumptions?: Record<string, boolean>;
235
}
236
```