0
# Script Attributes
1

2
Apply standard HTML script attributes (async, defer, module) to webpack-generated script tags based on configurable patterns.
3

4
## Capabilities
5

6
### Async Attribute
7

8
Configure scripts to load asynchronously without blocking HTML parsing.
9

10
```javascript { .api }
11
/**
12
 * Configure async attribute application
13
 * @param pattern - Pattern(s) to match script files for async loading
14
 */
15
async?: PatternConfig;
16

17
interface PatternConfig {
18
  test: string | RegExp | Array<string | RegExp>;
19
}
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
// All scripts async
26
new ScriptExtHtmlWebpackPlugin({
27
  defaultAttribute: 'async'
28
})
29

30
// Specific scripts async
31
new ScriptExtHtmlWebpackPlugin({
32
  async: 'chunk1.js'
33
})
34

35
// Multiple scripts async
36
new ScriptExtHtmlWebpackPlugin({
37
  async: ['chunk1.js', 'chunk2.js']
38
})
39

40
// Pattern-based async
41
new ScriptExtHtmlWebpackPlugin({
42
  async: /chunk.*\.js$/
43
})
44

45
// Advanced configuration
46
new ScriptExtHtmlWebpackPlugin({
47
  async: {
48
    test: [/^chunk/, 'vendor.js']
49
  }
50
})
51
```
52

53
### Defer Attribute
54

55
Configure scripts to defer execution until after document parsing is complete.
56

57
```javascript { .api }
58
/**
59
 * Configure defer attribute application
60
 * @param pattern - Pattern(s) to match script files for deferred loading
61
 */
62
defer?: PatternConfig;
63
```
64

65
**Usage Examples:**
66

67
```javascript
68
// Single script deferred
69
new ScriptExtHtmlWebpackPlugin({
70
  defer: 'analytics.js'
71
})
72

73
// Multiple scripts deferred
74
new ScriptExtHtmlWebpackPlugin({
75
  defer: ['analytics.js', 'tracking.js']
76
})
77

78
// Pattern-based defer
79
new ScriptExtHtmlWebpackPlugin({
80
  defer: /^(?!critical).*\.js$/
81
})
82

83
// Mixed configuration
84
new ScriptExtHtmlWebpackPlugin({
85
  sync: 'critical.js',
86
  defer: ['analytics.js', 'tracking.js'],
87
  defaultAttribute: 'async'
88
})
89
```
90

91
### Module Attribute
92

93
Configure scripts to load as ES6 modules with `type="module"`.
94

95
```javascript { .api }
96
/**
97
 * Configure module attribute application
98
 * @param pattern - Pattern(s) to match script files for module loading
99
 */
100
module?: PatternConfig;
101
```
102

103
**Usage Examples:**
104

105
```javascript
106
// ES6 module scripts
107
new ScriptExtHtmlWebpackPlugin({
108
  module: 'app.mjs'
109
})
110

111
// Multiple module scripts
112
new ScriptExtHtmlWebpackPlugin({
113
  module: ['app.mjs', 'utils.mjs']
114
})
115

116
// Pattern-based modules
117
new ScriptExtHtmlWebpackPlugin({
118
  module: /\.mjs$/
119
})
120
```
121

122
### Sync Attribute
123

124
Explicitly configure scripts to load synchronously (default behavior).
125

126
```javascript { .api }
127
/**
128
 * Configure sync script handling
129
 * @param pattern - Pattern(s) to match script files for synchronous loading
130
 */
131
sync?: PatternConfig;
132
```
133

134
**Usage Examples:**
135

136
```javascript
137
// Ensure critical scripts remain sync when default is async
138
new ScriptExtHtmlWebpackPlugin({
139
  sync: 'critical.js',
140
  defaultAttribute: 'async'
141
})
142

143
// Multiple sync scripts
144
new ScriptExtHtmlWebpackPlugin({
145
  sync: ['critical.js', 'polyfills.js'],
146
  defaultAttribute: 'defer'
147
})
148
```
149

150
### Default Attribute
151

152
Set the default loading behavior for scripts that don't match any specific patterns.
153

154
```javascript { .api }
155
/**
156
 * Default attribute for unmatched scripts
157
 */
158
defaultAttribute?: 'sync' | 'async' | 'defer';
159
```
160

161
**Usage Examples:**
162

163
```javascript
164
// All scripts async by default
165
new ScriptExtHtmlWebpackPlugin({
166
  defaultAttribute: 'async'
167
})
168

169
// All scripts deferred by default, except critical
170
new ScriptExtHtmlWebpackPlugin({
171
  sync: 'critical.js',
172
  defaultAttribute: 'defer'
173
})
174

175
// Sync by default (standard behavior)
176
new ScriptExtHtmlWebpackPlugin({
177
  defaultAttribute: 'sync'  // This is the default
178
})
179
```
180

181
### Pattern Matching
182

183
The plugin supports flexible pattern matching for script selection.
184

185
```javascript { .api }
186
/**
187
 * Pattern types supported for script matching
188
 */
189
type PatternConfig = 
190
  | string                              // Exact filename match
191
  | RegExp                              // Regular expression match
192
  | Array<string | RegExp>              // Array of patterns
193
  | { test: string | RegExp | Array<string | RegExp> }; // Object form
194
```
195

196
**Pattern Examples:**
197

198
```javascript
199
// String pattern - exact match
200
async: 'bundle.js'
201

202
// RegExp pattern - flexible matching
203
async: /chunk.*\.js$/
204

205
// Array patterns - multiple matches
206
async: ['chunk1.js', 'chunk2.js', /vendor/]
207

208
// Object form - explicit test property
209
async: {
210
  test: [/chunk/, 'bundle.js']
211
}
212

213
// Complex patterns
214
new ScriptExtHtmlWebpackPlugin({
215
  inline: 'runtime.js',
216
  sync: [/imp(1|2){1,3}/, 'initial'],
217
  defer: ['slow', /big.*andslow/],
218
  module: [/^((?!sync).)*/, 'mod'],
219
  defaultAttribute: 'async'
220
})
221
```
222

223
### Script Processing Order
224

225
The plugin uses a precedence model to ensure consistent behavior when multiple patterns match the same script:
226

227
1. **Inline**: If a script matches the `inline` pattern, it will be inlined (highest priority)
228
2. **Sync**: If a script matches the `sync` pattern, it will have no attribute, unless it matched condition 1
229
3. **Async**: If a script matches the `async` pattern, it will have the `async` attribute, unless it matched conditions 1 or 2
230
4. **Defer**: If a script matches the `defer` pattern, it will have the `defer` attribute, unless it matched conditions 1, 2, or 3
231
5. **Default attribute**: If a script doesn't match any previous conditions, it gets the `defaultAttribute`
232

233
The `module` attribute is independent of conditions 2-5, but will be ignored if the script is inlined.
234

235
**Precedence Example:**
236

237
```javascript
238
new ScriptExtHtmlWebpackPlugin({
239
  inline: 'app.js',      // Takes precedence - script will be inlined
240
  sync: 'app.js',        // Ignored - inline takes precedence
241
  async: 'app.js',       // Ignored - inline takes precedence
242
  defaultAttribute: 'defer' // Applied to other scripts
243
})
244
```