next-ssr-network-log

Chrome DevTools-like Network panel for Next.js SSR, React Server Components, Route Handlers, Server Actions, and API Routes.

Why?

Browser DevTools only show client-side requests. Server-side fetch() and axios requests are invisible. This package lets you inspect every server-side request in real time.

Features

• Automatic fetch interception - Monkey patches global.fetch with zero config
• Axios support - Automatically attaches request/response interceptors
• Manual logging API - Log database queries, file reads, and any non-fetch operations
• Live updates - WebSocket-based real-time request streaming
• Chrome DevTools-like UI - Network panel with filters, search, timing, and JSON viewer
• Timeline/Waterfall - Visual request timing similar to Chrome
• Performance insights - Slow requests, duplicates, error rates
• Copy utilities - Copy as cURL, fetch, or axios
• Production safe - Automatically disabled in production
• Plugin architecture - Extend with database, Redis, GraphQL plugins

Quick Start

npm install next-ssr-network-log

Option 1: Zero Config (Recommended)

Create instrumentation.ts at your project root:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('next-ssr-network-log/register');
  }
}

Enable in next.config.mjs:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
};
export default nextConfig;

That's it. Run npm run dev and open http://localhost:4789 to see the inspector.

Option 2: Manual Setup

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { networkInspector } = await import('next-ssr-network-log');
    networkInspector({
      port: 4789,
      maxLogs: 1000,
      ignore: ['/_next', '/favicon.ico'],
    });
  }
}

Option 3: Next.js Config Wrapper

// next.config.mjs
import { withNetworkInspector } from 'next-ssr-network-log/next';

export default withNetworkInspector({
  // your existing next config
}, {
  port: 4789,
  maxLogs: 1000,
});

Configuration

interface InspectorConfig {
  enabled: boolean;      // Enable/disable (default: true in dev, false in prod)
  port: number;          // Inspector UI port (default: 4789)
  maxLogs: number;       // Max stored requests (default: 1000)
  ignore: string[];      // URL patterns to ignore
  plugins: Plugin[];     // Custom plugins
}

Production Mode

Disabled by default. Enable with environment variable:

ENABLE_SSR_NETWORK=true npm start

Supported Next.js Features

| Feature | Support | |---------|---------| | Server Components | ✅ | | Route Handlers | ✅ | | Server Actions | ✅ | | API Routes | ✅ | | getServerSideProps | ✅ | | generateMetadata | ✅ | | Middleware | ⚠️ Experimental |

Inspector UI

The UI runs at http://localhost:4789 and provides:

• Request List - Method, status, duration, size, URL
• Filters - GET, POST, PUT, DELETE, PATCH, 2xx, 3xx, 4xx, 5xx
• Search - Text and regex URL filtering
• Details Panel - General, Headers, Request, Response, Timing, Preview
• JSON Viewer - Collapsible tree with syntax highlighting
• Waterfall - Visual request timeline
• Performance - Slow requests, duplicates, error rates
• Export - Download requests as JSON
• Dark Mode - Toggle light/dark theme
• Copy Utilities - Copy as cURL, fetch, or axios

Manual Logging (for non-fetch calls)

The package automatically intercepts fetch() and axios calls. For other operations like database queries, file reads, or custom operations, use the manual logging API:

logRequest

import { logRequest } from 'next-ssr-network-log';

// Log a database query
const start = Date.now();
const posts = await db.posts.findMany();
const duration = Date.now() - start;

logRequest({
  method: 'QUERY',
  url: 'postgresql://localhost:5432/mydb/posts',
  statusCode: 200,
  responseBody: posts,
  duration,
  source: 'database',
  type: 'prisma',
});

withTiming

Wrap any async operation with automatic timing and logging:

import { withTiming } from 'next-ssr-network-log';

// Automatically logs timing and result
const posts = await withTiming(
  { method: 'QUERY', url: 'db:posts', source: 'database', type: 'prisma' },
  () => db.posts.findMany()
);

logRequest Options

interface LogRequestOptions {
  method: string;          // 'GET', 'POST', 'QUERY', 'READ', etc.
  url: string;             // URL or identifier
  headers?: Record<string, string>;
  body?: any;              // Request body
  statusCode?: number;     // Response status (default: 200)
  responseHeaders?: Record<string, string>;
  responseBody?: any;      // Response data
  duration?: number;       // Duration in ms
  source?: string;         // 'database', 'file', 'cache', etc.
  type?: string;           // 'prisma', 'redis', 'fs', etc.
  route?: string;          // Next.js route
  error?: string;          // Error message
}

Examples

Database Query:

import { logRequest } from 'next-ssr-network-log';

const start = Date.now();
const users = await prisma.user.findMany();
logRequest({
  method: 'SELECT',
  url: 'prisma:user/findMany',
  statusCode: 200,
  responseBody: users,
  duration: Date.now() - start,
  source: 'database',
  type: 'prisma',
});

File Read:

import { logRequest } from 'next-ssr-network-log';
import fs from 'fs/promises';

const start = Date.now();
const data = await fs.readFile('./data.json', 'utf-8');
logRequest({
  method: 'READ',
  url: 'file://./data.json',
  statusCode: 200,
  responseBody: JSON.parse(data),
  duration: Date.now() - start,
  source: 'filesystem',
  type: 'fs',
});

Redis Cache:

import { logRequest } from 'next-ssr-network-log';

const start = Date.now();
const cached = await redis.get('user:1');
logRequest({
  method: 'GET',
  url: 'redis://user:1',
  statusCode: cached ? 200 : 404,
  responseBody: cached,
  duration: Date.now() - start,
  source: 'cache',
  type: 'redis',
});

External API with manual control:

import { logRequest } from 'next-ssr-network-log';

const id = logRequest({
  method: 'POST',
  url: 'https://api.example.com/data',
  body: { key: 'value' },
  source: 'external',
});

// Later, update with response
const response = await fetch('https://api.example.com/data', { ... });
const data = await response.json();

logRequest({
  method: 'POST',
  url: 'https://api.example.com/data',
  statusCode: response.status,
  responseBody: data,
  duration: 150,
  source: 'external',
});

Plugins

import { registerPlugin } from 'next-ssr-network-log';

const prismaPlugin = {
  name: 'prisma',
  version: '1.0.0',
  install(api) {
    api.addInterceptor({
      name: 'prisma-queries',
      match: (url) => url.startsWith('prisma://'),
      transform: (req) => ({ ...req, type: 'prisma' }),
    });
  },
};

registerPlugin(prismaPlugin);

Exports

| Import | What | |--------|------| | next-ssr-network-log | Main API (networkInspector, logRequest, withTiming, etc.) | | next-ssr-network-log/register | Auto-register entry point | | next-ssr-network-log/next | withNetworkInspector config wrapper | | next-ssr-network-log/plugins | Plugin API |

Examples

• App Router
• Pages Router

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Development mode
pnpm dev

# Run tests
pnpm test

# Lint
pnpm lint

How It Works

1. Monkey-patches global.fetch and attaches axios interceptors
2. Every server-side request is captured with metadata (URL, headers, body, timing)
3. Requests are stored in memory and broadcast via WebSocket
4. Inspector UI connects to WebSocket and renders requests in real time
5. Works with Server Components, Route Handlers, Server Actions, API Routes

License

MIT

Author

rkd1180

Repository

https://github.com/RKD1180/next-ssr-network