@iron-stack/devtools

Live development dashboard and observability toolkit -- real-time request tracing, tRPC call logging, Socket.IO event monitoring, Zustand state inspection, and TanStack Query tracking. All streamed to a browser-based dashboard.

Installation

npm install @iron-stack/devtools

Quick Start

Server

import { DevServer, registerRequestTracing, registerSocketLogging, createTrpcDevMiddleware } from '@iron-stack/devtools/server';

const devServer = new DevServer({ port: 4000 });
devServer.start();

// Trace all HTTP requests
registerRequestTracing(fastify, devServer);

// Log all Socket.IO events
registerSocketLogging(io, devServer);

// Log all tRPC procedure calls
const devMiddleware = createTrpcDevMiddleware(devServer);
// Use as tRPC middleware: t.procedure.use(devMiddleware)

Open http://localhost:4000 to view the live dashboard.

Client

import { createDevReporter, attachQueryLogger, devtoolsMiddleware } from '@iron-stack/devtools/client';

// 1. Create the reporter (batches events to the dev server)
const reporter = createDevReporter({ serverUrl: 'http://localhost:4000' });

// 2. Log TanStack Query state changes
const unsubscribe = attachQueryLogger(queryClient, reporter);

// 3. Wrap Zustand stores for state inspection
import { create } from 'zustand';

const useMyStore = create(
  devtoolsMiddleware(reporter, 'myStore', (set, get) => ({
    count: 0,
    increment: () => set({ count: get().count + 1 }),
  }))
);

API Reference

@iron-stack/devtools (shared types)

| Export | Description | |---|---| | DevEvent | Base event interface streamed to the dashboard | | DevEventType | Union of all event types (request, trpc, socket, client, etc.) | | RequestTrace | HTTP request trace data | | TrpcTrace | tRPC procedure call trace | | DbQueryTrace | Database query log entry | | ClientStateSnapshot | Client-side store state snapshot | | ClientQueryState | TanStack Query state snapshot |

@iron-stack/devtools/server

| Export | Description | |---|---| | DevServer | WebSocket-based dev server with built-in HTML dashboard | | DevServer.start() | Start the HTTP + WebSocket server | | DevServer.stop() | Shut down the server | | DevServer.emit(event) | Emit a custom event to the dashboard | | DevServer.createEvent(type, source, data, traceId?) | Factory for creating DevEvent objects | | registerRequestTracing(fastify, devServer) | Fastify hook that traces all HTTP request start/end with timing | | createTrpcDevMiddleware(devServer) | Returns a tRPC middleware that logs every procedure call | | registerSocketLogging(io, devServer) | Logs all Socket.IO connections, disconnections, and events | | DevServerConfig | Configuration interface for DevServer |

@iron-stack/devtools/client

| Export | Description | |---|---| | createDevReporter(config?) | Creates a batched event reporter that sends data to the dev server | | attachQueryLogger(queryClient, reporter) | Subscribes to TanStack Query cache and mutation events. Returns cleanup function | | devtoolsMiddleware(reporter, storeName, creator) | Zustand middleware that reports every state change to the dashboard | | createZustandDevtools | Legacy alias for devtoolsMiddleware | | DevReporter | Type for the reporter returned by createDevReporter | | DevReporterConfig | Configuration interface for the reporter |

Configuration

DevServerConfig

| Option | Type | Default | Description | |---|---|---|---| | port | number | 4000 | Port for the dashboard HTTP/WebSocket server | | maxHistory | number | 1000 | Max events kept in memory for new dashboard connections | | appBundleId | string | "" | iOS app bundle ID (for simulator controls in dashboard) | | appPath | string | "" | Path to built .app (for simulator install from dashboard) |

DevReporterConfig

| Option | Type | Default | Description | |---|---|---|---| | serverUrl | string | "http://localhost:4000" | DevServer URL | | batchIntervalMs | number | 500 | How often to flush batched events | | devOnly | boolean | true | Only report in __DEV__ mode | | deviceId | string | auto-generated | Unique device identifier for multi-device testing |

Dashboard Features

The built-in browser dashboard at http://localhost:{port} provides:

• Request timeline -- every HTTP request with status, duration, and trace ID
• tRPC inspector -- procedure calls with input, timing, and errors
• Socket.IO monitor -- connections, disconnections, and all events in real-time
• State viewer -- live Zustand store state with change highlighting
• Query viewer -- TanStack Query cache status across all queries
• Simulator controls -- boot, install, and launch on iOS simulators from the browser
• State editing -- modify Zustand state and TanStack Query data from the dashboard

License

MIT