0
# @vitejs/plugin-legacy
1

2
@vitejs/plugin-legacy is a Vite plugin that provides comprehensive legacy browser support by automatically generating SystemJS-compatible chunks and polyfills. It enables modern Vite applications to run in browsers that don't support native ESM modules, dynamic imports, or import.meta.
3

4
## Package Information
5

6
- **Package Name**: @vitejs/plugin-legacy
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vitejs/plugin-legacy`
10

11
## Core Imports
12

13
```typescript
14
import legacy from '@vitejs/plugin-legacy';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const legacy = require('@vitejs/plugin-legacy');
21
// Or using destructuring
22
const { default: legacy } = require('@vitejs/plugin-legacy');
23
```
24

25
## Basic Usage
26

27
```typescript
28
import { defineConfig } from 'vite';
29
import legacy from '@vitejs/plugin-legacy';
30

31
export default defineConfig({
32
  plugins: [
33
    legacy({
34
      targets: ['defaults', 'not IE 11'],
35
    }),
36
  ],
37
});
38
```
39

40
Note: Terser must be installed as a peer dependency:
41

42
```bash
43
npm install -D terser
44
```
45

46
## Architecture
47

48
@vitejs/plugin-legacy implements a comprehensive legacy browser support system through:
49

50
- **Build Configuration**: Automatically configures Vite build settings for legacy and modern builds
51
- **Dual Bundle Generation**: Creates both modern ESM bundles and legacy SystemJS bundles
52
- **Polyfill Detection**: Uses Babel preset-env to automatically detect and inject required polyfills
53
- **HTML Injection**: Conditionally loads legacy bundles using `nomodule` script tags
54
- **Code Transformation**: Transforms modern JavaScript to legacy-compatible code using Babel
55

56
## Capabilities
57

58
### Main Plugin Function
59

60
Creates Vite plugins for legacy browser support with automatic polyfill detection and dual bundle generation.
61

62
```typescript { .api }
63
/**
64
 * Main plugin factory function that creates legacy browser support plugins
65
 * @param options - Configuration options for legacy browser support
66
 * @returns Array of three Vite plugins for complete legacy support
67
 */
68
function viteLegacyPlugin(options?: Options): Plugin[];
69
```
70

71
[Plugin Configuration](./configuration.md)
72

73
### Polyfill Detection
74

75
Analyzes code to detect required polyfills for specified browser targets.
76

77
```typescript { .api }
78
/**
79
 * Detects required polyfills by analyzing code with Babel preset-env
80
 * @param code - JavaScript/TypeScript code to analyze
81
 * @param targets - Browser targets for polyfill detection
82
 * @param assumptions - Babel assumptions for code analysis
83
 * @param list - Set to populate with discovered polyfill imports
84
 */
85
function detectPolyfills(
86
  code: string,
87
  targets: any,
88
  assumptions: Record<string, boolean>,
89
  list: Set<string>
90
): Promise<void>;
91
```
92

93
[Polyfill Detection](./polyfills.md)
94

95
### CSP Hash Values
96

97
SHA-256 hashes for Content Security Policy script-src allowlist.
98

99
```typescript { .api }
100
/**
101
 * Array of SHA-256 hash values for inline scripts used by the plugin
102
 * Use these in your CSP script-src directive to allow plugin-generated inline scripts
103
 */
104
const cspHashes: string[];
105
```
106

107
[CSP Configuration](./csp.md)
108

109
### CommonJS Compatibility
110

111
The plugin provides full CommonJS compatibility through a dedicated export.
112

113
```typescript { .api }
114
/**
115
 * CommonJS-compatible version of the plugin with all exports
116
 * Includes viteLegacyPlugin as default, plus detectPolyfills and cspHashes
117
 */
118
const viteLegacyPluginCjs: typeof viteLegacyPlugin & {
119
  default: typeof viteLegacyPlugin;
120
  detectPolyfills: typeof detectPolyfills;
121
  cspHashes: typeof cspHashes;
122
};
123
```
124

125
## Types
126

127
```typescript { .api }
128
interface Options {
129
  /** Browser targets for legacy builds (default: 'defaults') */
130
  targets?: string | string[] | Record<string, string>;
131
  /** Browser targets for modern builds */
132
  modernTargets?: string | string[];
133
  /** Polyfill configuration (default: true) */
134
  polyfills?: boolean | string[];
135
  /** Additional polyfills for legacy builds */
136
  additionalLegacyPolyfills?: string[];
137
  /** Additional polyfills for modern builds */
138
  additionalModernPolyfills?: string[];
139
  /** Modern polyfill configuration (default: false) */
140
  modernPolyfills?: boolean | string[];
141
  /** Generate legacy SystemJS chunks (default: true) */
142
  renderLegacyChunks?: boolean;
143
  /** Use external SystemJS loading (default: false) */
144
  externalSystemJS?: boolean;
145
  /** Generate modern ESM chunks (default: true) */
146
  renderModernChunks?: boolean;
147
  /** Babel assumptions for code transformation (default: {}) */
148
  assumptions?: Record<string, boolean>;
149
}
150
```