1.0.3 • Published 5 months ago

express-port-switcher v1.0.3

Weekly downloads
-
License
MIT
Repository
github
Last release
5 months ago

Express Port Switcher

npm version GitHub

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

1.0.3

5 months ago

1.0.2

5 months ago

1.0.1

5 months ago

1.0.0

5 months ago