tessl/npm-reload
Node.js module to refresh and reload your code in your browser when your code changes.
—
express-integration.mddocs/
Express Integration
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.
Capabilities
Reload Function
Main function for integrating reload functionality into Express applications.
/**
* Integrate reload functionality into an Express application
* @param app - Express application instance
* @param opts - Optional configuration options
* @param server - Optional HTTP server instance (legacy parameter, deprecated)
* @returns Object with reload control methods
*/
function reload(app, opts?, server?): ReloadReturn;Parameters:
app(object, required): Express application instanceopts(object, optional): Configuration optionsserver(object, optional): HTTP server instance (legacy compatibility)
Usage Examples:
const express = require('express');
const reload = require('reload');
const app = express();
// Basic integration
const reloadServer = reload(app);
// With custom options
const reloadServer = reload(app, {
port: 9857,
verbose: true,
route: '/dev/reload.js'
});
// With WebSocket server delayed start
const reloadServer = reload(app, {
webSocketServerWaitStart: true
});
// Start WebSocket server when ready
reloadServer.startWebSocketServer();
app.listen(3000);Manual Reload Triggering
Manually trigger browser reload for all connected clients.
/**
* Manually trigger reload for all connected browsers
* No parameters required
* @returns void
*/
reload(): void;Usage Example:
const fs = require('fs');
const reloadServer = reload(app);
// Watch for file changes and trigger reload
fs.watchFile('./views/index.html', () => {
console.log('File changed, reloading...');
reloadServer.reload();
});WebSocket Server Control
Control WebSocket server startup for advanced integration scenarios.
/**
* Start the WebSocket server manually
* Only active when webSocketServerWaitStart option is true
* @returns void
*/
startWebSocketServer(): void;Usage Example:
const reloadServer = reload(app, {
webSocketServerWaitStart: true
});
// Later in your application startup
setTimeout(() => {
console.log('Starting WebSocket server...');
reloadServer.startWebSocketServer();
}, 2000);WebSocket Server Access
Direct access to the underlying WebSocket server for advanced usage.
/**
* WebSocket server instance
* Provides direct access to WebSocket server methods and events
* Type: import('ws').Server | undefined (undefined until server starts)
*/
wss: import('ws').Server | undefined;Usage Example:
const reloadServer = reload(app);
// Access WebSocket server directly
reloadServer.wss.on('connection', (ws) => {
console.log('Client connected');
ws.on('close', () => {
console.log('Client disconnected');
});
});
// Check number of connected clients (ensure server is started first)
if (reloadServer.wss) {
console.log(`Connected clients: ${reloadServer.wss.clients.size}`);
}Configuration Options
Port Configuration
Configure the WebSocket server port.
interface PortOption {
/** WebSocket server port (default: 9856) */
port?: number;
}Default: 9856 Usage: Set a custom port for the WebSocket server to avoid conflicts.
Route Configuration
Configure the route path for serving the reload client script.
interface RouteOption {
/** Route path for serving reload client script (default: '/reload/reload.js') */
route?: string;
}Default: '/reload/reload.js' Usage: Customize the script route path. The route will automatically append 'reload.js' if not present.
WebSocket Server Startup Control
Control when the WebSocket server starts.
interface WebSocketStartOption {
/** Delay WebSocket server start until startWebSocketServer() is called (default: false) */
webSocketServerWaitStart?: boolean;
}Default: false Usage: Delay WebSocket server startup for complex initialization scenarios.
Verbose Logging
Enable detailed logging for debugging.
interface VerboseOption {
/** Enable verbose logging on server and client (default: false) */
verbose?: boolean;
}Default: false Usage: Enable detailed logging for troubleshooting connection and reload issues.
Integration with Process Managers
Reload works seamlessly with Node.js process managers:
Supervisor Integration
supervisor -e "js,html,css" app.jsNodemon Integration
{
"scripts": {
"dev": "nodemon app.js"
}
}Forever Integration
forever -w app.jsClient-Side Requirements
The reload functionality requires including the client script in your HTML pages:
<!DOCTYPE html>
<html>
<head>
<title>My App</title>
</head>
<body>
<h1>Hello World</h1>
<!-- Include reload script before closing body tag -->
<script src="/reload/reload.js"></script>
</body>
</html>Note: The script path must match the configured route option.
Error Handling
The reload system handles various error conditions:
- WebSocket connection failures: Client automatically attempts to reconnect
- Server restart detection: Uses WebSocket connection closure to detect restarts
- Browser compatibility: Requires WebSocket support (modern browsers)
- Port conflicts: WebSocket server will fail if port is already in use
Legacy Compatibility
The reload function supports legacy parameter patterns for backward compatibility:
// Legacy usage (deprecated but supported)
// Order: httpServerOrPort, expressApp, verboseLogging
reload(server, app, verboseLogging);
// Modern usage (recommended)
reload(app, { verbose: verboseLogging });Note: Legacy usage will show a deprecation warning and it is recommended to upgrade to the new parameter format.
Internal API (CLI Mode Only)
When reload is used in CLI mode (via the reload-server.js), additional methods are available:
interface ReloadReturnCLI extends ReloadReturn {
/** Get the reload client script code (CLI mode only) */
reloadClientCode(): string;
}Usage: This method is used internally by the CLI server to serve the reload client code and is not available in Express integration mode.
Install with Tessl CLI
npx tessl i tessl/npm-reload