0
# Express Integration
1

2
Express integration provides WebSocket-based reload functionality for existing Express applications. The reload middleware creates server-side routes and WebSocket connections to enable automatic browser refreshing during development.
3

4
## Capabilities
5

6
### Reload Function
7

8
Main function for integrating reload functionality into Express applications.
9

10
```javascript { .api }
11
/**
12
 * Integrate reload functionality into an Express application
13
 * @param app - Express application instance
14
 * @param opts - Optional configuration options
15
 * @param server - Optional HTTP server instance (legacy parameter, deprecated)
16
 * @returns Object with reload control methods
17
 */
18
function reload(app, opts?, server?): ReloadReturn;
19
```
20

21
**Parameters:**
22

23
- `app` (object, required): Express application instance
24
- `opts` (object, optional): Configuration options
25
- `server` (object, optional): HTTP server instance (legacy compatibility)
26

27
**Usage Examples:**
28

29
```javascript
30
const express = require('express');
31
const reload = require('reload');
32

33
const app = express();
34

35
// Basic integration
36
const reloadServer = reload(app);
37

38
// With custom options
39
const reloadServer = reload(app, {
40
  port: 9857,
41
  verbose: true,
42
  route: '/dev/reload.js'
43
});
44

45
// With WebSocket server delayed start
46
const reloadServer = reload(app, {
47
  webSocketServerWaitStart: true
48
});
49
// Start WebSocket server when ready
50
reloadServer.startWebSocketServer();
51

52
app.listen(3000);
53
```
54

55
### Manual Reload Triggering
56

57
Manually trigger browser reload for all connected clients.
58

59
```javascript { .api }
60
/**
61
 * Manually trigger reload for all connected browsers
62
 * No parameters required
63
 * @returns void
64
 */
65
reload(): void;
66
```
67

68
**Usage Example:**
69

70
```javascript
71
const fs = require('fs');
72
const reloadServer = reload(app);
73

74
// Watch for file changes and trigger reload
75
fs.watchFile('./views/index.html', () => {
76
  console.log('File changed, reloading...');
77
  reloadServer.reload();
78
});
79
```
80

81
### WebSocket Server Control
82

83
Control WebSocket server startup for advanced integration scenarios.
84

85
```javascript { .api }
86
/**
87
 * Start the WebSocket server manually
88
 * Only active when webSocketServerWaitStart option is true
89
 * @returns void
90
 */
91
startWebSocketServer(): void;
92
```
93

94
**Usage Example:**
95

96
```javascript
97
const reloadServer = reload(app, {
98
  webSocketServerWaitStart: true
99
});
100

101
// Later in your application startup
102
setTimeout(() => {
103
  console.log('Starting WebSocket server...');
104
  reloadServer.startWebSocketServer();
105
}, 2000);
106
```
107

108
### WebSocket Server Access
109

110
Direct access to the underlying WebSocket server for advanced usage.
111

112
```javascript { .api }
113
/**
114
 * WebSocket server instance
115
 * Provides direct access to WebSocket server methods and events
116
 * Type: import('ws').Server | undefined (undefined until server starts)
117
 */
118
wss: import('ws').Server | undefined;
119
```
120

121
**Usage Example:**
122

123
```javascript
124
const reloadServer = reload(app);
125

126
// Access WebSocket server directly
127
reloadServer.wss.on('connection', (ws) => {
128
  console.log('Client connected');
129
  
130
  ws.on('close', () => {
131
    console.log('Client disconnected');
132
  });
133
});
134

135
// Check number of connected clients (ensure server is started first)
136
if (reloadServer.wss) {
137
  console.log(`Connected clients: ${reloadServer.wss.clients.size}`);
138
}
139
```
140

141
## Configuration Options
142

143
### Port Configuration
144

145
Configure the WebSocket server port.
146

147
```javascript { .api }
148
interface PortOption {
149
  /** WebSocket server port (default: 9856) */
150
  port?: number;
151
}
152
```
153

154
**Default:** 9856
155
**Usage:** Set a custom port for the WebSocket server to avoid conflicts.
156

157
### Route Configuration
158

159
Configure the route path for serving the reload client script.
160

161
```javascript { .api }
162
interface RouteOption {
163
  /** Route path for serving reload client script (default: '/reload/reload.js') */
164
  route?: string;
165
}
166
```
167

168
**Default:** '/reload/reload.js'
169
**Usage:** Customize the script route path. The route will automatically append 'reload.js' if not present.
170

171
### WebSocket Server Startup Control
172

173
Control when the WebSocket server starts.
174

175
```javascript { .api }
176
interface WebSocketStartOption {
177
  /** Delay WebSocket server start until startWebSocketServer() is called (default: false) */
178
  webSocketServerWaitStart?: boolean;
179
}
180
```
181

182
**Default:** false
183
**Usage:** Delay WebSocket server startup for complex initialization scenarios.
184

185
### Verbose Logging
186

187
Enable detailed logging for debugging.
188

189
```javascript { .api }
190
interface VerboseOption {
191
  /** Enable verbose logging on server and client (default: false) */
192
  verbose?: boolean;
193
}
194
```
195

196
**Default:** false
197
**Usage:** Enable detailed logging for troubleshooting connection and reload issues.
198

199
## Integration with Process Managers
200

201
Reload works seamlessly with Node.js process managers:
202

203
### Supervisor Integration
204

205
```bash
206
supervisor -e "js,html,css" app.js
207
```
208

209
### Nodemon Integration
210

211
```json
212
{
213
  "scripts": {
214
    "dev": "nodemon app.js"
215
  }
216
}
217
```
218

219
### Forever Integration
220

221
```bash
222
forever -w app.js
223
```
224

225
## Client-Side Requirements
226

227
The reload functionality requires including the client script in your HTML pages:
228

229
```html
230
<!DOCTYPE html>
231
<html>
232
<head>
233
  <title>My App</title>
234
</head>
235
<body>
236
  <h1>Hello World</h1>
237
  
238
  <!-- Include reload script before closing body tag -->
239
  <script src="/reload/reload.js"></script>
240
</body>
241
</html>
242
```
243

244
**Note:** The script path must match the configured route option.
245

246
## Error Handling
247

248
The reload system handles various error conditions:
249

250
- **WebSocket connection failures**: Client automatically attempts to reconnect
251
- **Server restart detection**: Uses WebSocket connection closure to detect restarts
252
- **Browser compatibility**: Requires WebSocket support (modern browsers)
253
- **Port conflicts**: WebSocket server will fail if port is already in use
254

255
## Legacy Compatibility
256

257
The reload function supports legacy parameter patterns for backward compatibility:
258

259
```javascript
260
// Legacy usage (deprecated but supported)
261
// Order: httpServerOrPort, expressApp, verboseLogging
262
reload(server, app, verboseLogging);
263

264
// Modern usage (recommended)
265
reload(app, { verbose: verboseLogging });
266
```
267

268
**Note:** Legacy usage will show a deprecation warning and it is recommended to upgrade to the new parameter format.
269

270
## Internal API (CLI Mode Only)
271

272
When reload is used in CLI mode (via the reload-server.js), additional methods are available:
273

274
```javascript { .api }
275
interface ReloadReturnCLI extends ReloadReturn {
276
  /** Get the reload client script code (CLI mode only) */
277
  reloadClientCode(): string;
278
}
279
```
280

281
**Usage:** This method is used internally by the CLI server to serve the reload client code and is not available in Express integration mode.