0
# Resource Hints
1
2
Generate preload and prefetch link tags for initial and dynamically loaded scripts to optimize loading performance.
3
4
## Capabilities
5
6
### Preload Resource Hints
7
8
Generate `<link rel="preload">` tags for high-priority scripts that should be loaded immediately.
9
10
```javascript { .api }
11
/**
12
* Configure preload resource hints
13
* @param config - Configuration for preload hints
14
*/
15
preload?: ResourceHintConfig;
16
17
interface ResourceHintConfig {
18
test: string | RegExp | Array<string | RegExp>;
19
chunks?: 'initial' | 'async' | 'all';
20
}
21
```
22
23
**Usage Examples:**
24
25
```javascript
26
// Preload critical scripts
27
new ScriptExtHtmlWebpackPlugin({
28
preload: 'critical.js'
29
})
30
31
// Preload multiple scripts
32
new ScriptExtHtmlWebpackPlugin({
33
preload: ['critical.js', 'app.js']
34
})
35
36
// Pattern-based preloading
37
new ScriptExtHtmlWebpackPlugin({
38
preload: /^critical.*\.js$/
39
})
40
41
// Preload with chunk specification
42
new ScriptExtHtmlWebpackPlugin({
43
preload: {
44
test: /\.js$/,
45
chunks: 'initial'
46
}
47
})
48
```
49
50
### Prefetch Resource Hints
51
52
Generate `<link rel="prefetch">` tags for lower-priority scripts that should be loaded when the browser is idle.
53
54
```javascript { .api }
55
/**
56
* Configure prefetch resource hints
57
* @param config - Configuration for prefetch hints
58
*/
59
prefetch?: ResourceHintConfig;
60
```
61
62
**Usage Examples:**
63
64
```javascript
65
// Prefetch analytics scripts
66
new ScriptExtHtmlWebpackPlugin({
67
prefetch: 'analytics.js'
68
})
69
70
// Prefetch lazy-loaded chunks
71
new ScriptExtHtmlWebpackPlugin({
72
prefetch: {
73
test: /lazy.*\.js$/,
74
chunks: 'async'
75
}
76
})
77
78
// Combined preload and prefetch
79
new ScriptExtHtmlWebpackPlugin({
80
preload: 'critical.js', // High priority
81
prefetch: 'analytics.js' // Low priority
82
})
83
```
84
85
### Chunk Targeting
86
87
Control which webpack chunks should have resource hints generated.
88
89
```javascript { .api }
90
/**
91
* Chunk types for resource hint generation
92
*/
93
type ChunkType = 'initial' | 'async' | 'all';
94
95
interface ResourceHintConfig {
96
test: string | RegExp | Array<string | RegExp>;
97
chunks?: ChunkType;
98
}
99
```
100
101
**Chunk Types:**
102
103
- **`initial`**: Entry point chunks loaded immediately (default)
104
- **`async`**: Dynamically imported chunks loaded on demand
105
- **`all`**: Both initial and async chunks
106
107
**Usage Examples:**
108
109
```javascript
110
// Preload initial chunks only (default)
111
new ScriptExtHtmlWebpackPlugin({
112
preload: {
113
test: /\.js$/,
114
chunks: 'initial'
115
}
116
})
117
118
// Prefetch async chunks for better UX
119
new ScriptExtHtmlWebpackPlugin({
120
prefetch: {
121
test: /\.js$/,
122
chunks: 'async'
123
}
124
})
125
126
// Preload all chunks
127
new ScriptExtHtmlWebpackPlugin({
128
preload: {
129
test: /critical/,
130
chunks: 'all'
131
}
132
})
133
```
134
135
### Generated HTML Output
136
137
Resource hints are inserted as `<link>` tags in the document head.
138
139
**Preload example:**
140
```html
141
<head>
142
<link rel="preload" href="critical.js" as="script">
143
<script src="critical.js" async></script>
144
</head>
145
```
146
147
**Prefetch example:**
148
```html
149
<head>
150
<link rel="prefetch" href="analytics.js" as="script">
151
<script src="analytics.js" async></script>
152
</head>
153
```
154
155
### Performance Optimization Strategies
156
157
**Preload for Critical Path:**
158
Use preload for scripts needed immediately for first paint or core functionality.
159
160
```javascript
161
new ScriptExtHtmlWebpackPlugin({
162
preload: 'critical.js',
163
async: 'critical.js' // Load async but preloaded
164
})
165
```
166
167
**Prefetch for Route-Based Code Splitting:**
168
Use prefetch for route chunks that users are likely to navigate to.
169
170
```javascript
171
new ScriptExtHtmlWebpackPlugin({
172
prefetch: {
173
test: /route-.*\.js$/,
174
chunks: 'async'
175
}
176
})
177
```
178
179
**Combined Strategy:**
180
Use both preload and prefetch for optimal loading performance.
181
182
```javascript
183
new ScriptExtHtmlWebpackPlugin({
184
// High priority - needed immediately
185
preload: {
186
test: ['critical.js', 'app.js'],
187
chunks: 'initial'
188
},
189
// Low priority - nice to have ready
190
prefetch: {
191
test: /^(?!critical|app).*\.js$/,
192
chunks: 'async'
193
},
194
// Make async chunks async loading
195
async: {
196
test: /\.js$/,
197
chunks: 'async'
198
}
199
})
200
```
201
202
### Browser Compatibility
203
204
Resource hints are supported in modern browsers with graceful degradation:
205
206
- **Preload**: Chrome 50+, Firefox 85+, Safari 11.1+
207
- **Prefetch**: Chrome 8+, Firefox 2+, Safari 11.1+
208
209
### Integration with Script Attributes
210
211
Resource hints work seamlessly with script attributes and other plugin features.
212
213
```javascript
214
// Complete performance optimization setup
215
new ScriptExtHtmlWebpackPlugin({
216
// Inline critical runtime
217
inline: 'runtime.js',
218
219
// Preload and async load critical scripts
220
preload: 'critical.js',
221
async: 'critical.js',
222
223
// Prefetch future routes
224
prefetch: {
225
test: /route-.*\.js$/,
226
chunks: 'async'
227
},
228
229
// Custom CORS attributes
230
custom: [{
231
test: /\.js$/,
232
attribute: 'crossorigin',
233
value: 'anonymous'
234
}]
235
})
236
```
237
238
### Resource Hint Validation
239
240
The plugin automatically validates resource hint configurations and ensures proper hint generation.
241
242
```javascript { .api }
243
/**
244
* Determines if resource hints should be added
245
* @param options - Plugin options
246
* @returns Whether resource hints are configured
247
*/
248
function shouldAddResourceHints(options: PluginOptions): boolean;
249
```
250
251
**Error Handling:**
252
The plugin will skip resource hint generation if:
253
- No test patterns are specified
254
- Patterns don't match any assets
255
- Invalid chunk configuration is provided