next-http-inspector

v0.2.11

Published

6 months ago

Next Http Inspector - Interceptors for Next.js with WebSocket logging and monitoring (dev-only).

0High
0Medium
0Low

jhonparra94

nextjs instrumentation interceptors logger monitoring websocket debug development dev-tools

Next Http Inspector

Fetch interceptor for Next.js that connects directly to external WebSocket servers (dev-only).

This package provides a fetch interceptor that captures HTTP requests and responses, connecting directly to external WebSocket servers for real-time monitoring.

🎯 Focus

This package connects directly to external WebSocket servers using only the ws library. It does not require any external packages and creates its own WebSocket client connections.

✨ Features

🔍 Fetch Interceptor: Captures all HTTP requests and responses
📡 Direct WebSocket Connection: Connects directly to external servers
🛡️ Development Only: Automatically disabled in production
🚀 Zero External Dependencies: Only requires ws library
🔒 Single Initialization: Prevents multiple initializations automatically

🚀 Installation

⚠️ Development Only: This package is designed exclusively for development environments. Do not install in production.

npm install --save-dev next-http-inspector

📖 Usage

For Next.js

Initialize in your root layout (server-side only):

// app/layout.tsx (or pages/_app.tsx for Pages Router)
import { initFetchServerInterceptor } from 'next-http-inspector';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  // Initialize only on server side
  if (typeof window === 'undefined') {
    initFetchServerInterceptor({
      websocket: { enabled: true, port: 8080 },
      http: { enabled: true, host: 'localhost', port: 3001, endpoint: '/api/logs' }
    });
  }

  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

Start external servers (in a separate terminal):

# Install the server globally (one-time setup)
npm install -g next-http-inspector-server

# Start the server
next-inspector-server --ui-port 3001 --ws-port 8080

Start your Next.js app:

npm run dev

Access the monitoring UI:

Open http://localhost:3001/ui in your browser.

Configuration Options

initFetchServerInterceptor({
  websocket: {
    enabled: true,          // Enable WebSocket connection
    port: 8080             // WebSocket port
  },
  http: {
    enabled: true,         // Enable HTTP fallback
    host: 'localhost',     // HTTP server host
    port: 3001,            // HTTP server port
    endpoint: '/api/logs'  // HTTP endpoint
  },
  fetch: global.fetch  // Optional: custom fetch function
});

🏗️ Architecture

┌─────────────────────────────────────┐
│           Next.js App               │
│  ┌─────────────────────────────────┐│
│  │     Interceptors Package        ││
│  │  ┌─────────────────────────────┐││
│  │  │  Fetch Interceptor          │││
│  │  └─────────────────────────────┘││
│  └─────────────────────────────────┘│
└─────────────────────────────────────┘
                    │
                    │ Direct WebSocket Client
                    ▼
┌─────────────────────────────────────┐
│    External Server Package          │
│  ┌─────────────────────────────────┐│
│  │  WebSocket Server (port 8080)   ││
│  │  UI Server (port 3001)          ││
│  └─────────────────────────────────┘│
└─────────────────────────────────────┘

Key Points:

This package creates its own WebSocket client connections
No external package dependencies required
Direct connection to external WebSocket servers
Ultra-clean separation of concerns
Single initialization prevents duplicate setup

🔧 Development

Build

npm run build

Development Mode

npm run dev

📦 Package Structure

src/
├── index.ts                    # Main initFetchServerInterceptor function
├── types.ts                    # TypeScript definitions
└── interceptors/
    └── fetchInterceptor.ts      # HTTP request/response interceptor

🔗 Related Packages

next-http-inspector-server - External WebSocket and UI servers

🛠️ Troubleshooting

No Data Appearing in UI

Check external servers are running:

next-inspector-server --ui-port 3001 --ws-port 8080

Verify ports match:
- WebSocket port in initFetchServerInterceptor() should match --ws-port
- UI port should match --ui-port
Check logs:
- Look for "🚀 Initializing Fetch Server Interceptor..." in console
- Verify interceptor is enabled: "✅ Fetch Server Interceptor initialized successfully!"

Initialization Issues

The package automatically prevents multiple initializations. If you need to reinitialize:

Restart your Next.js app:
```
# Stop app (Ctrl+C)
npm run dev
```

Ensure initialization happens only on server side:

if (typeof window === 'undefined') {
 initFetchServerInterceptor({ ... });

}


### Connection Issues

If WebSocket connection fails:

1. **Check server is running**:
```bash
curl http://localhost:3001/ui

Verify port availability:
```
lsof -i :8080
```
Check connection logs:
- Look for WebSocket connection messages in console
- HTTP fallback will be used automatically if WebSocket fails

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

📞 Support

If you encounter any issues or have questions, please open an issue on our GitHub repository.