🚀 local-debug-proxy

local-debug-proxy is a lightweight HTTP + WebSocket debugging proxy for Express and NestJS applications that lets you forward incoming API and socket requests to another backend (local or remote) at runtime, without changing your application code or redeploying.

It’s designed for debugging, development, and temporary routing, not as permanent infrastructure.

✨ What It Does (In One Line)

Receive a request in one environment → execute it in another → return the response transparently.

Your server URL remains unchanged — only where the code executes changes.

🔥 Use Cases for local-debug-proxy

1️⃣ Debug Production Issues Using Local Code

Client → Server → Local Machine → Server → Client

Some bugs only appear in the server environment. Instead of redeploying with console.log:

• Server receives the request (HTTP or WebSocket)
• Proxy forwards it directly to your local backend
• Code executes locally with full debugger and hot-reload access
• Response flows back transparently!

2️⃣ Run Local Backend Logic Behind a Server URL

Frontend teams depend on a stable server URL dev.api.myapp.com, but backend logic is still changing locally.

• Frontend continues calling the stable server URL
• Server forwards requests to your local backend
• Frontend stays unblocked while backend tests locally!

3️⃣ Temporarily Forward Server Traffic for Deep Inspection

Enable proxy at runtime to observe EXACT request/response flows without changing infrastructure. Completely zero downtime and fully reversible.

📦 Installation

npm install local-debug-proxy

⚙️ Express Example (HTTP + WebSockets / Socket.IO)

import http from "http";
import express from "express";
import { Server } from "socket.io";
import { createLocalDebugProxy, attachWebSocketProxy } from "local-debug-proxy";

const app = express();
const server = http.createServer(app);

// 1. Add HTTP proxy middleware
app.use(
  createLocalDebugProxy({
    enabled: true,
    mountPath: "/proxy",
    bypass: ["/health"],
    log: true,
  })
);

// 2. Initialize Socket.IO (Must happen BEFORE attachWebSocketProxy)
const io = new Server(server, { cors: { origin: "*" } });

io.on("connection", (socket) => {
  console.log("Client connected locally:", socket.id);
});

// 3. Attach WebSocket proxy (Must be LAST!)
attachWebSocketProxy(server, { log: true });

server.listen(3000, () => {
  console.log("Express server running on http://localhost:3000");
});

🦅 NestJS Example (HTTP + WebSockets)

In a NestJS application, apply the middleware globally and attach the WebSocket listener to the underlying HTTP server.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { createLocalDebugProxy, attachWebSocketProxy } from 'local-debug-proxy';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // 1. Add HTTP Proxy Middleware
  app.use(
    createLocalDebugProxy({
      enabled: process.env.NODE_ENV !== "production",
      mountPath: "/proxy",
      log: true,
    })
  );

  // Wait for NestJS to initialize engines (including WebSockets)
  await app.init(); 

  // 2. Get underlying raw HTTP server instance
  const server = app.getHttpServer();

  // 3. Attach WebSocket proxy LAST
  attachWebSocketProxy(server, { log: true });

  await app.listen(3000, () => {
    console.log("NestJS Server running on http://localhost:3000");
  });
}
bootstrap();

🌐 Proxy Control UI

Once enabled, visit the control panel at:

http://localhost:3000/proxy

From here you can Enable request forwarding, set target backend URLs dynamically, and Disable immediately. No restart required!

🛡️ Safety Notes

• Disabled by default: Acts as a true no-op middleware when turned off.
• Intended strictly for debugging workflows, not as a permanent reverse proxy.

👤 Author & Maintainer

Ankit Kumar

• GitHub: https://github.com/connectankit
• Email: [email protected]

Built and maintained with ❤️ for backend developers who want faster, safer debugging workflows.

🏷️ Keywords & Search Tags

debug-proxy express-proxy nestjs-proxy http-proxy websocket-proxy socketio-proxy local-debugging nodejs-debugging development-tools ngrok-alternative reverse-proxy