@mt0926/node-network-devtools 0.2.0 → 0.3.10

package/README.md

@@ -2,11 +2,11 @@
 
 # 🔍 Node Network DevTools
 
-**Monitor Node.js network requests with Chrome DevTools integration and built-in Web GUI**
+**A powerful, zero-config network debugging companion for Node.js.**  
+*Monitor all outgoing HTTP, HTTPS, and Fetch/Undici requests in a sleek, real-time Web GUI that feels just like Chrome DevTools.*
 
-[![npm version](https://img.shields.io/npm/v/node-network-devtools.svg)](https://www.npmjs.com/package/@mt0926/node-network-devtools)
+[![npm version](https://img.shields.io/npm/v/@mt0926/node-network-devtools.svg)](https://www.npmjs.com/package/@mt0926/node-network-devtools)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js Version](https://img.shields.io/node/v/node-network-devtools.svg)](https://nodejs.org)
 
 [English](#) | [中文文档](./README.zh-CN.md)
 
@@ -14,151 +14,104 @@
 
 ---
 
-## ⚠️ Development Tool Only
+## 🚀 Why Node Network DevTools?
 
-**This tool is designed for development environments only. Do NOT use in production!**
-
-- Uses Puppeteer to launch a minimal browser window for the GUI
-- Intercepts all network requests which may impact performance
-- Stores request/response data in memory
-- Not suitable for production workloads
-
-### Disabling in Production
-
-```javascript
-// Conditional installation
-if (process.env.NODE_ENV === 'development') {
-  await install();
-}
-```
-
-Or use environment variables:
-
-```bash
-# Disable GUI and auto-open
-NND_GUI_ENABLED=false NND_AUTO_OPEN=false node your-app.js
-```
+Tired of `console.log`ing every request and response? **Node Network DevTools** brings the familiarity of the browser's "Network" tab to your Node.js backend. Whether you're debugging external API calls, microservices, or Next.js server actions, you can now inspect every detail in real-time.
 
 ## ✨ Features
 
-- 🔍 **Dual Interception** - Supports both `http/https` modules and `undici/fetch` API
-- 🎯 **Zero Intrusion** - Auto-inject via `-r` or `--import`, no code changes needed
-- 🖥️ **Minimal Browser Window** - Puppeteer-powered compact GUI window (800x600)
-- 📊 **Built-in Web GUI** - Chrome DevTools-like interface with real-time updates
-- 🔗 **Request Tracing** - AsyncLocalStorage-based request correlation
-- 🛡️ **Security** - Auto-redact sensitive headers (Authorization, Cookie, etc.)
-- ⚡ **Next.js Compatible** - Preserves `next.revalidate`, `next.tags` options
-- 📦 **TypeScript** - Full TypeScript support with type definitions
+- 💎 **DevTools-like Experience** - A familiar, responsive Web GUI for inspecting headers, payloads, and responses.
+- 🔌 **Universal Interception** - Native support for `http/https` modules and modern `fetch/undici` (Node.js 18+).
+- 🛠️ **Zero Code Intrusion** - Plug it into your project with a single line of code or a simple CLI flag.
+- 🖥️ **Minimal Browser Window** - Automatically launches a compact, app-mode GUI window (using your system's Chrome, Edge, or Chromium).
+- 🔗 **Smart Request Tracing** - Automatically correlate related requests in a single business flow using `AsyncLocalStorage`.
+- 🛡️ **Built-in Redaction** - Keeps your secrets safe by auto-redacting sensitive headers like `Authorization` and `Cookie`.
+- ⚡ **Framework Ready** - Seamless integration with Next.js, Express, Fastify, and more.
+- 📦 **Dual Module Support** - Works out of the box with both **ESM** and **CommonJS**.
 
 ## 📸 Screenshots
 
 ### Web GUI Interface
 ![Web GUI](https://via.placeholder.com/800x450?text=Web+GUI+Screenshot)
 
-### Chrome DevTools Integration
-![Chrome DevTools](https://via.placeholder.com/800x450?text=Chrome+DevTools+Screenshot)
-
 ## 🚀 Quick Start
 
-### Installation
+### 1. Installation
 
 ```bash
-npm install node-network-devtools puppeteer
+npm install @mt0926/node-network-devtools
 # or
-pnpm add node-network-devtools puppeteer
-# or
-yarn add node-network-devtools puppeteer
+pnpm add @mt0926/node-network-devtools
 ```
 
-**Note**: Puppeteer is required for the GUI browser window. If not installed, you'll see a friendly error message with installation instructions.
-
-### Usage
+> **Note**: No extra dependencies like Puppeteer are required! It uses your system's existing browser.
 
-#### Method 1: CLI (Recommended)
+### 2. Usage (Recommended)
 
-```bash
-npx node-network-devtools your-script.js
-# or use the short alias
-npx nnd your-script.js
-```
+Just call `install()` at the very beginning of your application entry point.
 
-The CLI automatically injects the interceptor and opens the GUI.
-
-#### Method 2: Using `-r` flag
+**ESM:**
+```typescript
+import { install } from '@mt0926/node-network-devtools';
 
-```bash
-node -r node-network-devtools/register your-script.js
+await install(); // Call before any other imports that make network requests
 ```
 
-#### Method 3: Programmatic
-
-```typescript
-import { install } from 'node-network-devtools';
-
-await install();
+**CommonJS:**
+```javascript
+const { install } = require('@mt0926/node-network-devtools');
 
-// Your application code
-import express from 'express';
-const app = express();
-// ...
+(async () => {
+  await install();
+})();
 ```
 
-### Viewing Requests
-
-After starting your application:
+### 3. Advanced: Zero-Code Injection
 
-- **Web GUI** (Default): A minimal browser window will automatically open showing the GUI
-  - Compact window size (800x600 by default)
-  - Customizable window size and title
-  - No browser chrome or toolbars (app mode)
+If you don't want to modify your source code, you can use Node.js CLI arguments to inject the tool.
 
-To manually access the GUI, look for the URL in the console output:
+**ESM:**
+```bash
+node --import @mt0926/node-network-devtools/register your-script.js
 ```
-🚀 Node Network DevTools GUI started at http://localhost:9229
+
+**CommonJS:**
+```bash
+node -r @mt0926/node-network-devtools/register your-script.js
 ```
 
 ## 🖥️ Web GUI
 
-The built-in Web GUI provides a Chrome DevTools-like experience for monitoring network requests.
-
-### Minimal Browser Window
-
-The GUI opens in a minimal Puppeteer-controlled browser window:
-
-- **Compact Size**: Default 800x600, customizable via environment variables
-- **App Mode**: No browser chrome, toolbars, or address bar
-- **Custom Title**: Shows "Node Network DevTools" by default
-- **Fast Launch**: Opens in under 3 seconds
+Once started, a minimal browser window will automatically open showing the real-time request list.
 
-### Features
+- **Compact size** (800x600) for side-by-side debugging.
+- **Search & Filter** by URL, method, or status.
+- **Details Panel** for headers, payload, and response.
+- **Dark/Light** theme support.
 
-- 📋 **Request List** - Real-time display of all network requests
-- 🔍 **Search & Filter** - Filter by URL, method, status code, and type
-- 📝 **Details Panel** - View headers, payload, response, and timing
-- 🎨 **Theme Toggle** - Dark/Light theme support
-- ⏸️ **Pause/Resume** - Pause request capture for analysis
-- 🔄 **Real-time Updates** - WebSocket-based live updates
+If you need to access it manually, check the console output for the URL:
+`🚀 Node Network DevTools GUI started at http://localhost:9229`
 
 ### GUI Configuration
 
 ```bash
 # Customize window size
-NND_BROWSER_WIDTH=1024 NND_BROWSER_HEIGHT=768 npx nnd your-script.js
+NND_BROWSER_WIDTH=1024 NND_BROWSER_HEIGHT=768 node --import @mt0926/node-network-devtools/register your-script.js
 
 # Customize window title
-NND_BROWSER_TITLE="My App Network Monitor" npx nnd your-script.js
+NND_BROWSER_TITLE="My App Network Monitor" node --import @mt0926/node-network-devtools/register your-script.js
 
 # Specify GUI port
-NND_GUI_PORT=9230 npx nnd your-script.js
+NND_GUI_PORT=9230 node --import @mt0926/node-network-devtools/register your-script.js
 
 # Specify WebSocket port
-NND_WS_PORT=9231 npx nnd your-script.js
+NND_WS_PORT=9231 node --import @mt0926/node-network-devtools/register your-script.js
 
 # Disable GUI
-NND_GUI_ENABLED=false npx nnd your-script.js
+NND_GUI_ENABLED=false node --import @mt0926/node-network-devtools/register your-script.js
 
 # Disable auto-open browser
-NND_AUTO_OPEN=false npx nnd your-script.js
+NND_AUTO_OPEN=false node --import @mt0926/node-network-devtools/register your-script.js
 ```
 
 ## 🔧 Configuration
@@ -190,7 +143,7 @@ NND_AUTO_OPEN=false npx nnd your-script.js
 ### Programmatic Configuration
 
 ```typescript
-import { setConfig } from 'node-network-devtools';
+import { setConfig } from '@mt0926/node-network-devtools';
 
 setConfig({
   maxRequests: 500,
@@ -210,7 +163,7 @@ setConfig({
 ```typescript
 // Conditional installation based on environment
 if (process.env.NODE_ENV === 'development') {
-  const { install } = await import('node-network-devtools');
+  const { install } = await import('@mt0926/node-network-devtools');
   await install();
 }
 ```
@@ -257,9 +210,10 @@ Or configure in `package.json`:
 
 ### Express
 
+**ESM:**
 ```typescript
 import express from 'express';
-import { install } from 'node-network-devtools';
+import { install } from '@mt0926/node-network-devtools';
 
 await install();
 
@@ -267,33 +221,103 @@ const app = express();
 // Your routes...
 ```
 
+**CommonJS:**
+```javascript
+const express = require('express');
+const { install } = require('@mt0926/node-network-devtools');
+
+(async () => {
+  await install();
+  
+  const app = express();
+  // Your routes...
+})();
+```
+
 ### Other Frameworks
 
 Works with any Node.js framework! Just install the interceptor before your application code.
 
+## 📦 Module System Support
+
+This package supports both **ESM (ECMAScript Modules)** and **CommonJS** module systems, making it compatible with all Node.js projects.
+
+### ESM (ECMAScript Modules)
+
+Use `import` statements in projects with `"type": "module"` in package.json or `.mjs` files:
+
+```typescript
+import { install, getRequestStore } from '@mt0926/node-network-devtools';
+import '@mt0926/node-network-devtools/register';
+
+await install();
+const store = getRequestStore();
+```
+
+### CommonJS
+
+Use `require()` statements in traditional Node.js projects or `.cjs` files:
+
+```javascript
+const { install, getRequestStore } = require('@mt0926/node-network-devtools');
+require('@mt0926/node-network-devtools/register');
+
+(async () => {
+  await install();
+  const store = getRequestStore();
+})();
+```
+
+### TypeScript
+
+Full TypeScript support with type definitions for both module systems:
+
+```typescript
+import type { Config, IRequestStore } from '@mt0926/node-network-devtools';
+import { install, getRequestStore } from '@mt0926/node-network-devtools';
+
+const config: Config = {
+  maxRequests: 500,
+  guiEnabled: true,
+};
+
+await install();
+const store: IRequestStore = getRequestStore();
+```
+
+### Module Resolution
+
+The package uses Node.js [Conditional Exports](https://nodejs.org/api/packages.html#conditional-exports) to automatically provide the correct module format:
+
+- **ESM projects**: Resolves to `dist/esm/index.js`
+- **CommonJS projects**: Resolves to `dist/cjs/index.js`
+- **TypeScript**: Uses `dist/types/index.d.ts` for both
+
+No configuration needed - it just works! 🎉
+
 ## 📚 API Reference
 
 ### Main Exports
 
 ```typescript
 // Quick install
-import { install, startGUI, stopGUI } from 'node-network-devtools';
+import { install, startGUI, stopGUI } from '@mt0926/node-network-devtools';
 
 // Configuration
-import { getConfig, setConfig, resetConfig } from 'node-network-devtools';
+import { getConfig, setConfig, resetConfig } from '@mt0926/node-network-devtools';
 
 // Request store
-import { getRequestStore } from 'node-network-devtools';
+import { getRequestStore } from '@mt0926/node-network-devtools';
 
 // Context tracing
 import { 
   runWithTrace, 
   getCurrentTraceId,
   generateTraceId 
-} from 'node-network-devtools';
+} from '@mt0926/node-network-devtools';
 
 // Interceptors
-import { HttpPatcher, UndiciPatcher } from 'node-network-devtools';
+import { HttpPatcher, UndiciPatcher } from '@mt0926/node-network-devtools';
 ```
 
 ### Request Tracing
@@ -301,7 +325,7 @@ import { HttpPatcher, UndiciPatcher } from 'node-network-devtools';
 Correlate multiple requests in the same business flow:
 
 ```typescript
-import { runWithTrace, getRequestStore } from 'node-network-devtools';
+import { runWithTrace, getRequestStore } from '@mt0926/node-network-devtools';
 
 await runWithTrace('user-login', async () => {
   // These requests will be correlated with the same traceId
@@ -320,6 +344,7 @@ Check the [examples](./examples) directory for more usage examples:
 
 - [basic-http](./examples/basic-http) - Basic HTTP request monitoring
 - [fetch-api](./examples/fetch-api) - Fetch API monitoring
+- [commonjs-usage](./examples/commonjs-usage) - CommonJS module usage
 - [request-tracing](./examples/request-tracing) - Request tracing
 - [express-server](./examples/express-server) - Express server example
 - [programmatic-api](./examples/programmatic-api) - Programmatic API usage
@@ -331,7 +356,7 @@ Check the [examples](./examples) directory for more usage examples:
 2. **Undici Interception**: Uses `Agent.compose()` to register interceptors for fetch requests
 3. **Context Propagation**: Uses `AsyncLocalStorage` to pass TraceID through async call chains
 4. **Event Bridge**: Forwards intercepted requests to WebSocket clients for real-time GUI updates
-5. **Minimal Browser**: Uses Puppeteer to launch a compact browser window in app mode
+5. **Native Browser Launch**: Detects and launches your system's browser (Chrome/Edge/Chromium) in a dedicated app-mode window.
 
 ## 🤝 Contributing
 
@@ -369,7 +394,7 @@ MIT © [ddddd](https://github.com/dong0926)
 
 - 🐛 [Report Issues](https://github.com/dong0926/node-network-devtools/issues)
 - 💬 [Discussions](https://github.com/dong0926/node-network-devtools/discussions)
-- 📧 Email: your.email@example.com
+- 📧 Email: xx630133368@gmail.com
 
 ---