ServerReq

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

!ServerReq DevTools

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

``bash
npm install --save-dev serverreq
`

Usage

$3

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

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

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

export default nextConfig;
`

Step 2: Create an instrumentation file:

`ts
// 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:

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

export const GET = createSSEHandler();
`

Step 4: Add the DevTools component to your layout:

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

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (


{children}
{process.env.NODE_ENV === "development" && }


);
}
`

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

$3

For any Node.js application, use the CLI:

`bash

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
`

$3

`ts
import { install, configure } from "serverreq";

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

// Install interceptors
install();
`

DevTools Component Props

`tsx
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

$3

`
┌─────────────────────────────────────────────────────────────┐
│ 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) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
`

$3

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

CLI Options

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

Configuration

`ts
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