Doru Interceptoru

Small Node.js network interception library + CLI with a web UI.

• Intercepts http/https and fetch via @mswjs/interceptors
• Writes JSONL (default) or JSON captures
• Works with both CommonJS and ESM scripts

Requires Node 22+

Install

npm i -g doru
doru --ui <script>

# or just
npx doru --ui <script>

# development
bun i && bun run build

Try it out:

bun src/cli.ts --ui examples/basic.mjs
bun src/cli.ts --ui examples/basic.cjs
bun src/cli.ts --ui (which claude)

Development

Prerequisites

• Node.js 22+
• Bun (recommended) or npm

Setup

bun install

Scripts

| Command | Description | |---------|-------------| | bun run build | Build library, CLI, and UI | | bun run dev | Watch mode for library/CLI (tsup) | | bun run dev:ui | Vite dev server for UI (HMR) | | bun run type-check | TypeScript type checking | | bun run storybook | Component development UI |

UI Development

The web UI uses React + Vite. For hot module reloading:

# 1. start doru
 src/cli.ts --ui capture.jsonl

# 2. start Vite dev server and open open http://localhost:5173
bun run dev:ui

Vite proxies /api requests to the CLI server (port 3000).

CLI Development

# Watch mode - rebuilds on file changes
bun run dev

# Run CLI from source
bun src/cli.ts [options]

Project Structure

src/
├── index.ts          # Library entry
├── cli.ts            # CLI entry
├── core/             # Interceptor, config, storage
├── cli/              # Argument parsing, server
└── ui/react/         # React web UI

Library

Use doru programmatically in your Node.js application:

import { createInterceptor } from "doru";

const interceptor = createInterceptor({
  outputFile: "./capture.jsonl",
  format: "jsonl", // "jsonl" or "json"
  filters: {
    excludeHosts: ["localhost", "127.0.0.1"],
    methods: ["GET", "POST"],
  },
});
interceptor.start();

// your app code - all http/https/fetch calls are captured
await fetch("https://api.example.com/data");

interceptor.stop();

API

createInterceptor(config?)

Returns an interceptor instance with:

• start() — Begin intercepting network requests
• stop() — Stop intercepting and close output file
• updateConfig(config) — Update configuration at runtime
• getConfig() — Get current configuration

Configuration

interface InterceptorConfig {
  enabled: boolean;              // default: true
  outputFile: string;            // default: "./network-capture.jsonl"
  format: "json" | "jsonl";      // default: "jsonl"
  maxFileSize: number;           // default: 10MB
  debug: boolean;                // default: false (or DORU_DEBUG env)

  filters: {
    includeHosts: string[];      // only capture these hosts
    excludeHosts: string[];      // skip these hosts
    includePaths: string[];      // regex patterns to include
    excludePaths: string[];      // regex patterns to exclude
    methods: string[];           // e.g. ["GET", "POST"]
    statusCodes: {
      min: number | null;        // minimum status code
      max: number | null;        // maximum status code
    };
    minSize: number | null;      // minimum response size
    maxSize: number | null;      // maximum response size
  };

  performance: {
    bufferSize: number;          // default: 1024
    flushInterval: number;       // default: 1000ms
    compression: boolean;        // default: false
  };
}

CLI

Run script with network interception

doru run [options] <script> [-- <script-args>]

Runs a Node.js script with network interception enabled:

doru run server.js
doru run app.mjs -- --port 3000
doru run -o api.jsonl fetch-data.js

Live UI Mode

doru --ui <script> [-- <script-args>]

Runs a script with real-time web UI for monitoring:

doru --ui server.js
doru --ui app.mjs -- --port 8080

Explorer Mode

doru --ui <capture.json|jsonl>

Opens the web UI to explore an existing capture file:

doru --ui capture.jsonl
doru --ui network-capture.json

Options

| Option | Description | |--------|-------------| | -o, --output <file> | Output file (default: ./network-capture.jsonl) | | -f, --format <fmt> | json or jsonl (default: jsonl) | | -c, --config <file> | Config file path (JSON) | | --ui <path> | Explorer (capture file) or Live UI (script) | | --debug | Enable debug logs | | --max-file-size <size> | e.g. 10MB, 500KB | | --include-hosts <list> | Comma-separated hosts to capture | | --exclude-hosts <list> | Comma-separated hosts to skip | | --include-paths <list> | Comma-separated path patterns | | --exclude-paths <list> | Comma-separated path patterns | | --methods <list> | Comma-separated methods (e.g. GET,POST) | | --min-status <code> | Minimum status code (100-599) | | --max-status <code> | Maximum status code (100-599) | | -h, --help | Show help | | -v, --version | Show version |

Examples

# Basic capture
doru run server.js

# Custom output file and format
doru run -o api-calls.json -f json server.js

# Filter specific hosts
doru run --include-hosts api.example.com,cdn.example.com app.js

# Exclude localhost traffic
doru run --exclude-hosts localhost,127.0.0.1 app.js

# Only capture POST/PUT requests
doru run --methods POST,PUT app.js

# Only capture error responses
doru run --min-status 400 app.js

# Pass arguments to script
doru run server.js -- --port 3000 --env production

# Live UI with script
doru --ui server.js -- --port 3000

# Explore existing capture
doru --ui ./network-capture.jsonl