0
# CSP Configuration
1

2
Content Security Policy configuration for @vitejs/plugin-legacy inline scripts.
3

4
## Capabilities
5

6
### CSP Hash Values
7

8
Pre-computed SHA-256 hash values for all inline scripts generated by the plugin, required for strict CSP policies.
9

10
```typescript { .api }
11
/**
12
 * Array of SHA-256 hash values for inline scripts used by the plugin
13
 * These hashes should be added to your CSP script-src directive
14
 * @readonly
15
 */
16
const cspHashes: string[];
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import legacy, { cspHashes } from '@vitejs/plugin-legacy';
23

24
// Use in CSP header generation
25
const cspHashes = [
26
  'sha256-MS6/3FCg4WjP9gwgaBGwLpRCY6fZBgwmhVCdrPrNf3E=',
27
  'sha256-tQjf8gvb2ROOMapIxFvFAYBeUJ0v1HCbOcSmDNXGtDo=',
28
  'sha256-ZxAi3a7m9Mzbc+Z1LGuCCK5Xee6reDkEPRas66H9KSo=',
29
  'sha256-+5XkZFazzJo8n0iOP4ti/cLCMUudTf//Mzkb7xNPXIc=',
30
];
31

32
// Generate CSP header
33
const cspHeader = `script-src 'self' ${cspHashes.map(h => `'${h}'`).join(' ')}`;
34
```
35

36
### Dynamic CSP Header Generation
37

38
Generate CSP headers dynamically using the exported hash values.
39

40
**Implementation Example:**
41

42
```typescript
43
import { cspHashes } from '@vitejs/plugin-legacy';
44

45
// Helper function for generating CSP headers (not exported by plugin)
46
function generateCSPHeader(additionalSources: string[] = []): string {
47
  const baseSources = ["'self'"];
48
  const hashSources = cspHashes.map(hash => `'sha256-${hash}'`);
49
  const allSources = [...baseSources, ...hashSources, ...additionalSources];
50
  
51
  return `script-src ${allSources.join(' ')}`;
52
}
53

54
// Usage in server middleware
55
app.use((req, res, next) => {
56
  const cspHeader = generateCSPHeader(["'unsafe-eval'"]);
57
  res.setHeader('Content-Security-Policy', cspHeader);
58
  next();
59
});
60
```
61

62
### Inline Script Types
63

64
The plugin generates several types of inline scripts that require CSP allowlisting. These are internal to the plugin and not directly exported, but understanding them helps with CSP configuration.
65

66
### CSP Policy Examples
67

68
Complete CSP policy examples for different security requirements.
69

70
**Strict CSP (Recommended):**
71

72
```html
73
<meta http-equiv="Content-Security-Policy" content="
74
  default-src 'self';
75
  script-src 'self' 
76
    'sha256-MS6/3FCg4WjP9gwgaBGwLpRCY6fZBgwmhVCdrPrNf3E='
77
    'sha256-tQjf8gvb2ROOMapIxFvFAYBeUJ0v1HCbOcSmDNXGtDo='
78
    'sha256-ZxAi3a7m9Mzbc+Z1LGuCCK5Xee6reDkEPRas66H9KSo='
79
    'sha256-+5XkZFazzJo8n0iOP4ti/cLCMUudTf//Mzkb7xNPXIc=';
80
  style-src 'self' 'unsafe-inline';
81
  img-src 'self' data:;
82
">
83
```
84

85
**Development CSP (Less Strict):**
86

87
```html
88
<meta http-equiv="Content-Security-Policy" content="
89
  default-src 'self';
90
  script-src 'self' 'unsafe-eval'
91
    'sha256-MS6/3FCg4WjP9gwgaBGwLpRCY6fZBgwmhVCdrPrNf3E='
92
    'sha256-tQjf8gvb2ROOMapIxFvFAYBeUJ0v1HCbOcSmDNXGtDo='
93
    'sha256-ZxAi3a7m9Mzbc+Z1LGuCCK5Xee6reDkEPRas66H9KSo='
94
    'sha256-+5XkZFazzJo8n0iOP4ti/cLCMUudTf//Mzkb7xNPXIc=';
95
  style-src 'self' 'unsafe-inline';
96
">
97
```
98

99
### Version Compatibility
100

101
CSP hash values may change between plugin versions:
102

103
- Hash values are stable within patch versions
104
- Hash values may change in minor versions  
105
- Always regenerate CSP headers when updating plugin versions
106
- Pin to patch versions (using ~) if copying hashes manually
107
- Current hash values are valid for plugin version 7.2.1
108
- Recommended: Generate hashes dynamically from cspHashes export
109

110
**Version Pinning Example:**
111

112
```json
113
{
114
  "dependencies": {
115
    "@vitejs/plugin-legacy": "~7.2.1"
116
  }
117
}
118
```
119

120
### GlobalThis Polyfill
121

122
Special consideration for regenerator-runtime and globalThis. When using regenerator-runtime polyfill without globalThis support, add core-js globalThis polyfill to prevent CSP violations.
123

124
**Implementation:**
125

126
```typescript
127
legacy({
128
  additionalLegacyPolyfills: [
129
    // Prevents CSP violations in IE 11 and other browsers without globalThis
130
    'core-js/proposals/global-this',
131
  ],
132
});
133
```
134

135
### Server Configuration Examples
136

137
CSP configuration for different server environments.
138

139
**Express.js:**
140

141
```typescript
142
import express from 'express';
143
import { cspHashes } from '@vitejs/plugin-legacy';
144

145
const app = express();
146

147
app.use((req, res, next) => {
148
  const hashes = cspHashes.map(h => `'sha256-${h}'`).join(' ');
149
  const csp = `script-src 'self' ${hashes}`;
150
  res.setHeader('Content-Security-Policy', csp);
151
  next();
152
});
153
```
154

155
**Nginx:**
156

157
```nginx
158
location / {
159
    add_header Content-Security-Policy "script-src 'self' 'sha256-MS6/3FCg4WjP9gwgaBGwLpRCY6fZBgwmhVCdrPrNf3E=' 'sha256-tQjf8gvb2ROOMapIxFvFAYBeUJ0v1HCbOcSmDNXGtDo=' 'sha256-ZxAi3a7m9Mzbc+Z1LGuCCK5Xee6reDkEPRas66H9KSo=' 'sha256-+5XkZFazzJo8n0iOP4ti/cLCMUudTf//Mzkb7xNPXIc='";
160
}
161
```