npm package: @iron-stack/devtools
Description: 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.
Latest version: 1.0.0

# @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

```bash
npm install @iron-stack/devtools
```

## Quick Start

### Server

```ts
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

```ts
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