serverreq

v1.1.0

Published

4 months ago

Production-ready DevTools for intercepting HTTP/HTTPS requests in Node.js applications with React DevTools UI

0High
0Medium
0Low

ahmednnasser111

http https fetch interceptor request logging debugging cli nodejs nextjs devtools react socket.io

ServerReq

Production-ready DevTools for intercepting and visualizing HTTP/HTTPS requests in Node.js applications.

Features

🔍 HTTP/HTTPS Interception - Captures all fetch, http.request, and https.request calls
⚡ Real-time DevTools - Beautiful floating panel similar to React Query DevTools
🔒 Secret Masking - Automatically masks sensitive headers and body fields
🎯 Next.js Integration - First-class support for Next.js App Router
🚀 Zero Config CLI - Just prefix your command with serverreq
🔌 Socket.IO Transport - Reliable real-time communication

Installation

npm install --save-dev serverreq

Usage

Option 1: Next.js App Router (Recommended)

Step 1: Enable the instrumentation hook in next.config.ts:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    instrumentationHook: true,
  },
};

export default nextConfig;

Step 2: Create an instrumentation file:

// instrumentation.ts (in your project root)
export async function register() {
  if (process.env.NODE_ENV === "development") {
    const { setupDevTools } = await import("serverreq/nextjs");
    await setupDevTools();
  }
}

Step 3: Create the SSE API route for DevTools communication:

// app/api/devtools/stream/route.ts
import { createSSEHandler } from "serverreq/nextjs";

export const GET = createSSEHandler();

Step 4: Add the DevTools component to your layout:

// app/layout.tsx
import { ServerReqDevtools } from "serverreq/devtools";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        {process.env.NODE_ENV === "development" && <ServerReqDevtools />}
      </body>
    </html>
  );
}

That's it! The DevTools panel will appear as a floating button in the bottom-right corner.

Option 2: CLI Usage

For any Node.js application, use the CLI:

# Run any Node.js command with request interception
npx serverreq -- node server.js

# Next.js development
npx serverreq -- next dev

# With options
npx serverreq --format=json --exclude="localhost:3000" -- npm start

Option 3: Programmatic Usage

import { install, configure } from "serverreq";

// Configure options
configure({
  enabled: true,
  maskSecrets: true,
  excludeUrls: [/localhost:3000/],
});

// Install interceptors
install();

DevTools Component Props

<ServerReqDevtools
  socketUrl="http://localhost:4000" // Custom socket URL (auto-detected by default)
  defaultOpen={false} // Start with panel open
  position="bottom-right" // or "bottom-left"
/>

How It Works

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Next.js Server                        │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  HTTP Interceptor (fetch, http, https)                │   │
│  │            │                                          │   │
│  │            ▼                                          │   │
│  │     Event Bus (in-memory)                             │   │
│  │            │                                          │   │
│  │            ▼                                          │   │
│  │  Socket.IO Server (port 4000)  ◄────────────────────┐│   │
│  └──────────────────────────────────│───────────────────┘   │
└──────────────────────────────────────│──────────────────────┘
                                       │
                ┌──────────────────────┘
                │ WebSocket
                ▼
┌─────────────────────────────────────────────────────────────┐
│                         Browser                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Socket.IO Client                                     │   │
│  │       │                                               │   │
│  │       ▼                                               │   │
│  │  DevToolsStore (useSyncExternalStore)                 │   │
│  │       │                                               │   │
│  │       ▼                                               │   │
│  │  ServerReqDevtools (React Component)                  │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Key Design Decisions

Standalone Socket.IO Server - Runs on port 4000 to avoid conflicts with Next.js Turbopack
useSyncExternalStore - React 18 pattern for external state management
Singleton Store - Survives HMR and component remounts
Event Bus - Decouples interceptor from transport layer
Production Safety - Automatically disabled when NODE_ENV=production

CLI Options

| Option | Description | | ------------------------- | --------------------------------------- | | --format=<json\|pretty> | Output format (default: pretty for TTY) | | --no-mask | Disable secret masking | | --exclude=<pattern> | URL pattern to exclude (regex) | | --help, -h | Show help |

Configuration

interface ServerReqConfig {
  enabled: boolean; // Enable/disable (default: true in dev)
  format: "json" | "pretty"; // Output format
  maskSecrets: boolean; // Mask sensitive data (default: true)
  secretPatterns: RegExp[]; // Patterns to mask in body
  excludeUrls: RegExp[]; // URL patterns to exclude
  maxBodyLength: number; // Max body preview length (default: 1024)
}

License

MIT