devtools-instrumentation

devtools-instrumentation

Prerequisite: Read the devtools-event-client skill first for EventClient creation, event maps, and emit()/on() API.

Strategic placement of emit() calls inside a library to send high-value diagnostic data to TanStack Devtools panels. Maximum insight with minimum noise.

Key Insight

The event bus transparently bridges server/client and cross-tab boundaries. emit() on the server arrives on the client via WebSocket/SSE. emit() in one tab reaches other tabs via BroadcastChannel. No transport code needed -- just emit at the right place.

For prototyping, throw in many events. For production, consolidate down to the fewest events that carry the most information.

Where to Instrument

Emit at architecture boundaries, not inside implementation details:

1. Middleware/interceptor entry and exit -- wrap the chain, not each middleware
2. State transitions -- when state moves between logical phases (idle -> loading -> success/error)
3. Lifecycle hooks -- mount, unmount, connect, disconnect, ready
4. Error boundaries -- caught exceptions, retries, fallbacks
5. User-initiated actions processed -- after fully applied, not before

Do NOT emit from: internal utility functions, loop iterations, getter/setter accesses, intermediate computation steps.

Core Patterns

1. Middleware/Interceptor Instrumentation

Wrap the pipeline at the boundary, not each middleware individually.

import { EventClient } from '@tanstack/devtools-event-client'

type RouterEvents = {
  'request-processed': {
    id: string
    method: string
    path: string
    duration: number
    middlewareChain: Array<{ name: string; durationMs: number }>
    status: number
    error?: string
  }
}

class RouterDevtoolsClient extends EventClient<RouterEvents> {
  constructor() {
    super({
      pluginId: 'my-router',
      enabled: process.env.NODE_ENV !== 'production',
    })
  }
}

export const routerDevtools = new RouterDevtoolsClient()