1.0.3 • Published 5 months ago
express-port-switcher v1.0.3
Express Port Switcher
A smart port management tool that automatically tries to bind your Express server to a preferred port (e.g., port 3000), but if that port is already in use, it detects that and forwards incoming requests to an available port instead.
Features
- 🎯 Try to use preferred port first
- 🔄 Automatic port forwarding if preferred port is busy
- 🚀 Works with Express.js applications
- 📝 TypeScript support out of the box
- 🎣 Callback when port switching occurs
Installation
npm install express-port-switcher
Usage
import express from "express";
import { PortSwitcher } from "express-port-switcher";
const app = express();
app.get("/", (req, res) => {
res.send("Hello World!");
});
// Create a new PortSwitcher instance
const portSwitcher = new PortSwitcher({
preferredPort: 3000, // Default: 3000
maxAttempts: 100, // Default: 100
onPortSwitch: (preferredPort, actualPort) => {
console.log(
`Port ${preferredPort} was busy, forwarding to port ${actualPort}`
);
},
});
// Start the server
portSwitcher
.listen(app)
.then((port) => {
console.log(`Server is running on port ${port}`);
})
.catch((err) => {
console.error("Failed to start server:", err);
});
API Reference
PortSwitcher
Constructor Options
interface PortSwitcherOptions {
preferredPort?: number; // The port you'd prefer to use (default: 3000)
maxAttempts?: number; // Maximum number of ports to try (default: 100)
onPortSwitch?: (preferredPort: number, actualPort: number) => void; // Callback when port switching occurs
}
Methods
listen(app: Express): Promise<number>
- Starts the Express app on the preferred port, or forwards to an available port if occupied
- Returns a promise that resolves to the actual port number being used
getActualPort(): number | null
- Returns the actual port the server is running on
- Returns null if the server hasn't been started
close(): Promise<void>
- Closes both the proxy and the actual server
Utility Functions
The package also exports utility functions:
isPortAvailable(port: number): Promise<boolean>
- Checks if a specific port is available
findNextAvailablePort(startPort: number, maxAttempts?: number): Promise<number | null>
- Finds the next available port starting from startPort
- Returns null if no ports are available within maxAttempts
License
MIT