tessl/npm-reload
Node.js module to refresh and reload your code in your browser when your code changes.
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-reload@2.4.00
# Reload
1
2
Reload provides automatic browser refresh functionality for Node.js applications during development. It works by establishing a WebSocket connection between the browser and server, automatically refreshing the page when the server restarts. No browser plugins are required.
3
4
## Package Information
5
6
- **Package Name**: reload
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install reload` (local) or `npm install -g reload` (global)
10
11
## Core Imports
12
13
```javascript
14
const reload = require('reload');
15
```
16
17
For TypeScript with type definitions:
18
19
```typescript
20
import * as reload from 'reload';
21
```
22
23
## Basic Usage
24
25
### Express Integration (Recommended)
26
27
```javascript
28
const express = require('express');
29
const reload = require('reload');
30
31
const app = express();
32
33
// Set up your Express routes
34
app.get('/', (req, res) => {
35
res.send(`
36
<html>
37
<body>
38
<h1>Hello World</h1>
39
<script src="/reload/reload.js"></script>
40
</body>
41
</html>
42
`);
43
});
44
45
// Initialize reload
46
const reloadServer = reload(app);
47
48
app.listen(3000, () => {
49
console.log('Server running on port 3000');
50
});
51
```
52
53
### Command Line Usage
54
55
```bash
56
# Basic usage - serves current directory on port 8080
57
reload
58
59
# Open browser automatically and serve specific directory
60
reload -b -d ./public -p 3000
61
62
# Watch specific file types and directories
63
reload -e "html,js,css,json" -w ./src -d ./public
64
```
65
66
## Architecture
67
68
Reload operates in two distinct modes:
69
70
- **Express Middleware Mode**: Integrates with existing Express applications by adding reload routes and WebSocket server
71
- **Standalone CLI Mode**: Provides its own HTTP server with static file serving and automatic script injection
72
- **WebSocket Communication**: Uses WebSocket protocol for real-time communication between browser and server
73
- **File Watching**: Monitors file changes through process managers (supervisor, nodemon) or CLI file watching
74
75
The reload process works by:
76
1. Establishing WebSocket connection between browser client and Node.js server
77
2. Detecting server restarts (via WebSocket connection closure)
78
3. Automatically refreshing the browser page once the server comes back online
79
80
## Capabilities
81
82
### Express Integration
83
84
Core Express middleware functionality for integrating reload into existing web applications. Provides WebSocket server management and reload script serving.
85
86
```javascript { .api }
87
function reload(app, opts?, server?): ReloadReturn;
88
89
interface ReloadOptions {
90
port?: number; // WebSocket server port (default: 9856)
91
webSocketServerWaitStart?: boolean; // Delay WebSocket server start (default: false)
92
route?: string; // Route for reload script (default: '/reload/reload.js')
93
verbose?: boolean; // Enable verbose logging (default: false)
94
}
95
96
interface ReloadReturn {
97
reload(): void; // Manually trigger browser reload
98
startWebSocketServer(): void; // Start WebSocket server (when webSocketServerWaitStart is true)
99
wss: import('ws').Server | undefined; // WebSocket server instance (undefined until server starts)
100
}
101
```
102
103
[Express Integration](./express-integration.md)
104
105
### Command Line Interface
106
107
Standalone server with static file serving, file watching, and automatic browser opening. Ideal for static HTML development and simple projects.
108
109
Command line options for controlling server behavior, file watching, and browser integration.
110
111
```bash { .api }
112
reload [options]
113
114
Options:
115
-b, --browser # Open browser automatically
116
-n, --hostname [hostname] # Custom hostname (default: localhost)
117
-d, --dir [dir] # Directory to serve (default: current dir)
118
-w, --watch-dir [watch-dir] # Directory to watch for changes
119
-e, --exts [extensions] # File extensions to watch (default: html,js,css)
120
-p, --port [port] # Server port (default: 8080)
121
-s, --start-page [start-page] # Start page filename (default: index.html)
122
-f, --fallback [fallback] # Fallback to start page for missing routes
123
-v, --verbose [verbose] # Enable verbose logging
124
```
125
126
[Command Line Interface](./cli.md)
127
128
## Types
129
130
```javascript { .api }
131
interface ReloadOptions {
132
/** WebSocket server port (default: 9856) */
133
port?: number;
134
/** Delay WebSocket server start until startWebSocketServer() is called (default: false) */
135
webSocketServerWaitStart?: boolean;
136
/** Route path for serving reload client script (default: '/reload/reload.js') */
137
route?: string;
138
/** Enable verbose logging on server and client (default: false) */
139
verbose?: boolean;
140
}
141
142
interface ReloadReturn {
143
/** Manually trigger reload for all connected browsers */
144
reload(): void;
145
/** Start the WebSocket server (only when webSocketServerWaitStart is true) */
146
startWebSocketServer(): void;
147
/** WebSocket server instance for advanced usage (undefined until server starts) */
148
wss: import('ws').Server | undefined;
149
/** Get reload client script code (only available in CLI/server mode) */
150
reloadClientCode?(): string;
151
}
152
```