0
# Custom Attributes
1

2
Add arbitrary custom attributes to script elements for specialized use cases like CORS, CSP, or custom loading behavior.
3

4
## Capabilities
5

6
### Custom Attribute Configuration
7

8
Add custom attributes to script elements based on configurable patterns and values.
9

10
```javascript { .api }
11
/**
12
 * Array of custom attribute configurations
13
 */
14
custom?: CustomAttributeConfig[];
15

16
interface CustomAttributeConfig {
17
  test: string | RegExp | Array<string | RegExp>;
18
  attribute: string;
19
  value?: any;
20
}
21
```
22

23
**Usage Examples:**
24

25
```javascript
26
// Single custom attribute
27
new ScriptExtHtmlWebpackPlugin({
28
  custom: {
29
    test: /\.js$/,
30
    attribute: 'crossorigin',
31
    value: 'anonymous'
32
  }
33
})
34

35
// Multiple custom attributes
36
new ScriptExtHtmlWebpackPlugin({
37
  custom: [
38
    {
39
      test: /\.js$/,
40
      attribute: 'crossorigin', 
41
      value: 'anonymous'
42
    },
43
    {
44
      test: 'analytics.js',
45
      attribute: 'data-category',
46
      value: 'tracking'
47
    }
48
  ]
49
})
50
```
51

52
### Attribute Types and Values
53

54
Custom attributes support various value types for different use cases.
55

56
```javascript { .api }
57
/**
58
 * Custom attribute value types
59
 */
60
interface CustomAttributeConfig {
61
  test: string | RegExp | Array<string | RegExp>;
62
  attribute: string;
63
  value?: string | number | boolean | null | undefined;
64
}
65
```
66

67
**Value Examples:**
68

69
```javascript
70
new ScriptExtHtmlWebpackPlugin({
71
  custom: [
72
    // String value
73
    {
74
      test: /\.js$/,
75
      attribute: 'crossorigin',
76
      value: 'anonymous'
77
    },
78
    // Boolean value (true)
79
    {
80
      test: 'critical.js',
81
      attribute: 'async',
82
      value: true
83
    },
84
    // Boolean attribute (no value)
85
    {
86
      test: 'module.js',
87
      attribute: 'nomodule'
88
      // value defaults to true for boolean attributes
89
    },
90
    // Numeric value
91
    {
92
      test: 'versioned.js',
93
      attribute: 'data-version',
94
      value: 1.5
95
    }
96
  ]
97
})
98
```
99

100
### Common Use Cases
101

102
### CORS Configuration
103

104
Add Cross-Origin Resource Sharing attributes for CDN scripts.
105

106
```javascript
107
new ScriptExtHtmlWebpackPlugin({
108
  custom: {
109
    test: /\.js$/,
110
    attribute: 'crossorigin',
111
    value: 'anonymous'
112
  }
113
})
114
```
115

116
**Generated HTML:**
117
```html
118
<script src="app.js" crossorigin="anonymous"></script>
119
```
120

121
### Content Security Policy (CSP)
122

123
Add nonce attributes for Content Security Policy compliance.
124

125
```javascript
126
new ScriptExtHtmlWebpackPlugin({
127
  custom: {
128
    test: /\.js$/,
129
    attribute: 'nonce',
130
    value: 'abc123'
131
  }
132
})
133
```
134

135
**Generated HTML:**
136
```html
137
<script src="app.js" nonce="abc123"></script>
138
```
139

140
### Data Attributes
141

142
Add custom data attributes for analytics or application-specific metadata.
143

144
```javascript
145
new ScriptExtHtmlWebpackPlugin({
146
  custom: [
147
    {
148
      test: 'analytics.js',
149
      attribute: 'data-category',
150
      value: 'tracking'
151
    },
152
    {
153
      test: /chunk.*\.js$/,
154
      attribute: 'data-chunk-type',
155
      value: 'lazy'
156
    }
157
  ]
158
})
159
```
160

161
**Generated HTML:**
162
```html
163
<script src="analytics.js" data-category="tracking"></script>
164
<script src="chunk1.js" data-chunk-type="lazy"></script>
165
```
166

167
### Progressive Enhancement
168

169
Add attributes for progressive enhancement and feature detection.
170

171
```javascript
172
new ScriptExtHtmlWebpackPlugin({
173
  custom: [
174
    {
175
      test: 'modern.js',
176
      attribute: 'type',
177
      value: 'module'
178
    },
179
    {
180
      test: 'legacy.js', 
181
      attribute: 'nomodule',
182
      value: true
183
    }
184
  ]
185
})
186
```
187

188
**Generated HTML:**
189
```html
190
<script src="modern.js" type="module"></script>
191
<script src="legacy.js" nomodule></script>
192
```
193

194
### Pattern Matching for Custom Attributes
195

196
Custom attributes support the same flexible pattern matching as other plugin features.
197

198
```javascript { .api }
199
/**
200
 * Pattern matching options for custom attributes
201
 */
202
type TestPattern = 
203
  | string                              // Exact filename match
204
  | RegExp                              // Regular expression match  
205
  | Array<string | RegExp>;             // Array of patterns
206
```
207

208
**Pattern Examples:**
209

210
```javascript
211
new ScriptExtHtmlWebpackPlugin({
212
  custom: [
213
    // Exact match
214
    {
215
      test: 'specific-script.js',
216
      attribute: 'id',
217
      value: 'main-script'
218
    },
219
    // RegExp pattern
220
    {
221
      test: /^vendor-.*\.js$/,
222
      attribute: 'data-source',
223
      value: 'third-party'
224
    },
225
    // Multiple patterns
226
    {
227
      test: ['app.js', 'main.js', /^core/],
228
      attribute: 'data-priority',
229
      value: 'high'
230
    }
231
  ]
232
})
233
```
234

235
### Integration with Other Features
236

237
Custom attributes work alongside all other plugin features.
238

239
```javascript
240
// Complete configuration example
241
new ScriptExtHtmlWebpackPlugin({
242
  // Script attributes
243
  async: /chunk.*\.js$/,
244
  defer: 'analytics.js',
245
  
246
  // Resource hints
247
  preload: 'critical.js',
248
  prefetch: {
249
    test: /lazy.*\.js$/,
250
    chunks: 'async'
251
  },
252
  
253
  // Custom attributes
254
  custom: [
255
    // CORS for all scripts
256
    {
257
      test: /\.js$/,
258
      attribute: 'crossorigin',
259
      value: 'anonymous'
260
    },
261
    // Special handling for analytics
262
    {
263
      test: 'analytics.js',
264
      attribute: 'data-consent-required',
265
      value: 'true'
266
    },
267
    // Version tracking for app scripts
268
    {
269
      test: /^(app|main)/,
270
      attribute: 'data-version',
271
      value: '2.1.5'
272
    }
273
  ]
274
})
275
```
276

277
### Attribute Processing Order
278

279
Custom attributes are applied after script attribute processing to ensure they don't interfere with core functionality:
280

281
1. **Script inlining** (if configured)
282
2. **Standard attributes** (async, defer, module, sync)
283
3. **Resource hints** (preload, prefetch)
284
4. **Custom attributes** (applied last)
285

286
### Validation and Error Handling
287

288
The plugin validates custom attribute configurations and provides helpful error messages.
289

290
```javascript { .api }
291
/**
292
 * Validates custom attribute configuration
293
 * @param config - Custom attribute configuration
294
 * @returns Whether configuration is valid
295
 */
296
function validateCustomAttribute(config: CustomAttributeConfig): boolean;
297
```
298

299
**Common validation errors:**
300
- Missing `test` pattern
301
- Missing `attribute` name
302
- Invalid attribute names (must be valid HTML attribute names)
303

304
**Example error:**
305
```
306
ScriptExtHtmlWebpackPlugin: invalid configuration - custom attribute missing 'test' property
307
```