0
# Webpack Hot Middleware
1
2
Webpack Hot Middleware provides webpack hot module replacement (HMR) for custom server setups without requiring webpack-dev-server. It acts as a bridge between webpack's compilation process and browser clients using Server-Sent Events to communicate build updates and coordinate hot module replacement through webpack's HMR API.
3
4
## Package Information
5
6
- **Package Name**: webpack-hot-middleware
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev webpack-hot-middleware`
10
11
## Core Imports
12
13
```javascript
14
const webpackHotMiddleware = require("webpack-hot-middleware");
15
```
16
17
For client-side integration:
18
19
```javascript
20
// In webpack entry configuration
21
entry: {
22
main: ['webpack-hot-middleware/client', './src/main.js']
23
}
24
```
25
26
## Basic Usage
27
28
```javascript
29
const webpack = require('webpack');
30
const express = require('express');
31
const webpackDevMiddleware = require('webpack-dev-middleware');
32
const webpackHotMiddleware = require('webpack-hot-middleware');
33
34
const app = express();
35
const config = require('./webpack.config.js');
36
const compiler = webpack(config);
37
38
// Add webpack-dev-middleware
39
app.use(webpackDevMiddleware(compiler, {
40
publicPath: config.output.publicPath
41
}));
42
43
// Add webpack-hot-middleware
44
app.use(webpackHotMiddleware(compiler));
45
46
app.listen(3000);
47
```
48
49
## Architecture
50
51
Webpack Hot Middleware operates through several key components:
52
53
- **Server Middleware**: Express/Connect-compatible middleware that manages webpack compiler events and client connections
54
- **Event Stream**: Server-Sent Events (SSE) communication layer for real-time updates between server and clients
55
- **Client Runtime**: Browser-side JavaScript that connects to the event stream and applies HMR updates
56
- **Error Overlay**: Optional browser overlay displaying compilation errors and warnings
57
- **Update Processing**: Module update detection and application using webpack's HMR API
58
59
## Capabilities
60
61
### Server Middleware
62
63
The main middleware factory function that creates HMR middleware for a webpack compiler.
64
65
```javascript { .api }
66
/**
67
* Creates webpack hot middleware for a compiler instance
68
* @param {Object} compiler - webpack compiler instance
69
* @param {Object} opts - Configuration options
70
* @returns {Function} Express/Connect-compatible middleware with additional methods
71
*/
72
function webpackHotMiddleware(compiler, opts);
73
74
interface MiddlewareOptions {
75
/** Function for logging or false to disable (default: console.log) */
76
log?: Function | false;
77
/** Path for event stream endpoint (default: '/__webpack_hmr') */
78
path?: string;
79
/** Heartbeat interval in milliseconds (default: 10000) */
80
heartbeat?: number;
81
/** Stats configuration object (default: {}) */
82
statsOptions?: Object;
83
}
84
```
85
86
The middleware function includes additional methods:
87
88
```javascript { .api }
89
interface MiddlewareInstance {
90
/** Manually publish events to connected clients */
91
publish(payload: Object): void;
92
/** Close the middleware and clean up resources */
93
close(): void;
94
}
95
```
96
97
**Usage Example:**
98
99
```javascript
100
const webpackHotMiddleware = require('webpack-hot-middleware');
101
102
// Basic usage
103
const hotMiddleware = webpackHotMiddleware(compiler);
104
app.use(hotMiddleware);
105
106
// With options
107
const hotMiddleware = webpackHotMiddleware(compiler, {
108
log: console.log,
109
path: '/__webpack_hmr',
110
heartbeat: 10 * 1000
111
});
112
app.use(hotMiddleware);
113
114
// Manual event publishing
115
hotMiddleware.publish({
116
action: 'reload'
117
});
118
119
// Cleanup
120
hotMiddleware.close();
121
```
122
123
### Client Integration
124
125
Client-side module that connects to the HMR server and handles module updates.
126
127
```javascript { .api }
128
/**
129
* Client module exports when used as CommonJS module
130
*/
131
interface ClientExports {
132
/** Subscribe to all HMR events */
133
subscribeAll(handler: Function): void;
134
/** Subscribe to custom HMR events */
135
subscribe(handler: Function): void;
136
/** Replace default error overlay with custom implementation */
137
useCustomOverlay(customOverlay: Object): void;
138
/** Set client options and establish connection */
139
setOptionsAndConnect(overrides: Object): void;
140
}
141
```
142
143
**Usage Examples:**
144
145
```javascript
146
// As webpack entry (automatic connection)
147
entry: {
148
main: ['webpack-hot-middleware/client', './src/main.js']
149
}
150
151
// As module for custom handling
152
const client = require('webpack-hot-middleware/client');
153
154
client.subscribe(function(obj) {
155
if (obj.action === 'reload') {
156
window.location.reload();
157
}
158
});
159
160
client.subscribeAll(function(obj) {
161
console.log('HMR event:', obj);
162
});
163
```
164
165
### Client Configuration
166
167
Client behavior can be configured via query parameters when including in webpack entry.
168
169
```javascript { .api }
170
interface ClientOptions {
171
/** Event stream endpoint path (default: '/__webpack_hmr') */
172
path?: string;
173
/** Bundle name for multi-compiler mode */
174
name?: string;
175
/** Reconnection timeout in milliseconds (default: 20000) */
176
timeout?: number;
177
/** Enable/disable error overlay (default: true) */
178
overlay?: boolean;
179
/** Enable auto-reload on webpack stuck (default: false) */
180
reload?: boolean;
181
/** Disable informational logging (default: false) */
182
noInfo?: boolean;
183
/** Disable all console logging (default: false) */
184
quiet?: boolean;
185
/** Use webpack publicPath as path prefix (default: false) */
186
dynamicPublicPath?: boolean;
187
/** Auto-connect to server (default: true) */
188
autoConnect?: boolean;
189
/** Custom ANSI colors for overlay */
190
ansiColors?: Object;
191
/** Custom styles for error overlay */
192
overlayStyles?: Object;
193
/** Show overlay for warnings (default: false) */
194
overlayWarnings?: boolean;
195
}
196
```
197
198
**Configuration Examples:**
199
200
```javascript
201
// Basic client configuration
202
entry: {
203
main: [
204
'webpack-hot-middleware/client?path=/__webpack_hmr&timeout=20000&reload=true',
205
'./src/main.js'
206
]
207
}
208
209
// Multi-compiler configuration
210
module.exports = [
211
{
212
name: 'mobile',
213
entry: {
214
main: ['webpack-hot-middleware/client?name=mobile', 'mobile.js']
215
}
216
},
217
{
218
name: 'desktop',
219
entry: {
220
main: ['webpack-hot-middleware/client?name=desktop', 'desktop.js']
221
}
222
}
223
];
224
225
// Custom overlay colors and styles
226
const ansiColors = { red: '00FF00' };
227
const overlayStyles = { color: '#FF0000' };
228
const clientScript = 'webpack-hot-middleware/client?ansiColors=' +
229
encodeURIComponent(JSON.stringify(ansiColors)) +
230
'&overlayStyles=' + encodeURIComponent(JSON.stringify(overlayStyles));
231
```
232
233
### Error Overlay
234
235
Browser overlay system for displaying compilation errors and warnings.
236
237
```javascript { .api }
238
/**
239
* Creates customizable error overlay for browser
240
* @param {Object} options - Configuration with ansiColors and overlayStyles
241
* @returns {Object} Overlay instance with control methods
242
*/
243
function createOverlay(options: OverlayOptions): OverlayInstance;
244
245
interface OverlayOptions {
246
/** Custom ANSI color mappings */
247
ansiColors?: Object;
248
/** Custom CSS styles for overlay element */
249
overlayStyles?: Object;
250
}
251
252
interface OverlayInstance {
253
/** Display compilation problems in overlay */
254
showProblems(type: 'errors' | 'warnings', lines: string[]): void;
255
/** Remove overlay from DOM */
256
clear(): void;
257
}
258
```
259
260
**Usage Example:**
261
262
```javascript
263
const createOverlay = require('webpack-hot-middleware/client-overlay');
264
265
const overlay = createOverlay({
266
ansiColors: {
267
red: 'ff0000',
268
yellow: 'ffff00'
269
},
270
overlayStyles: {
271
fontSize: '14px',
272
fontFamily: 'Monaco, monospace'
273
}
274
});
275
276
// Show errors
277
overlay.showProblems('errors', [
278
'Module not found: Error: Cannot resolve module "missing-module"'
279
]);
280
281
// Clear overlay
282
overlay.clear();
283
```
284
285
### Helper Utilities
286
287
Utility functions used internally by the middleware.
288
289
```javascript { .api }
290
/**
291
* URL path matching utility
292
* @param {string} url - URL string to test
293
* @param {string} path - Path string to match against
294
* @returns {boolean} True if paths match
295
*/
296
function pathMatch(url: string, path: string): boolean;
297
```
298
299
## Event Protocol
300
301
The middleware communicates with clients using a defined event protocol over Server-Sent Events.
302
303
### Server to Client Events
304
305
```javascript { .api }
306
interface HMREvent {
307
/** Event action type */
308
action: 'building' | 'built' | 'sync';
309
/** Bundle name (for multi-compiler) */
310
name?: string;
311
/** Build completion time in milliseconds */
312
time?: number;
313
/** Build hash string */
314
hash?: string;
315
/** Compilation warnings */
316
warnings?: string[];
317
/** Compilation errors */
318
errors?: string[];
319
/** Module ID to name mapping */
320
modules?: Object;
321
}
322
```
323
324
### Event Types
325
326
- **building**: Emitted when webpack starts rebuilding
327
- **built**: Emitted when webpack completes a build
328
- **sync**: Emitted when a client first connects to sync current state
329
330
## Multi-Compiler Support
331
332
Webpack Hot Middleware supports webpack's multi-compiler mode for handling multiple webpack configurations simultaneously.
333
334
**Configuration:**
335
336
```javascript
337
// webpack.config.js
338
module.exports = [
339
{
340
name: 'client',
341
entry: {
342
main: ['webpack-hot-middleware/client?name=client', './src/client.js']
343
},
344
// ... other client config
345
},
346
{
347
name: 'server',
348
entry: {
349
main: ['webpack-hot-middleware/client?name=server', './src/server.js']
350
},
351
// ... other server config
352
}
353
];
354
355
// Server setup
356
const compiler = webpack(configs);
357
app.use(webpackHotMiddleware(compiler));
358
```
359
360
## Error Handling
361
362
The middleware handles various error conditions and provides fallback mechanisms:
363
364
- **Connection Loss**: Automatic reconnection with configurable timeout
365
- **Build Errors**: Error overlay display with ANSI color support
366
- **Update Failures**: Fallback to full page reload when HMR fails
367
- **Module Rejection**: Graceful handling of modules that can't be hot updated
368
369
## Webpack Configuration
370
371
Required webpack configuration for hot module replacement:
372
373
```javascript
374
// webpack.config.js
375
const webpack = require('webpack');
376
377
module.exports = {
378
plugins: [
379
new webpack.HotModuleReplacementPlugin()
380
],
381
entry: {
382
main: ['webpack-hot-middleware/client', './src/main.js']
383
}
384
};
385
```