--- title: Event System id: event-system --- The event system is how plugins communicate with the devtools UI and with the application. It is built on `EventClient`, a type-safe event emitter/listener from `@tanstack/devtools-event-client`. It is completely framework-agnostic. ## EventClient Basics Create a typed `EventClient` by extending the base class with your event map: ```ts import { EventClient } from '@tanstack/devtools-event-client' type MyEvents = { 'state-update': { count: number } 'action': { type: string } } class MyEventClient extends EventClient { constructor() { super({ pluginId: 'my-plugin' }) } } export const myEventClient = new MyEventClient() ``` The constructor accepts the following options: | Option | Type | Default | Description | | ------------------ | --------- | ------- | ---------------------------------------------------- | | `pluginId` | `string` | — | Required. Identifies this plugin in the event system. | | `debug` | `boolean` | `false` | Enable debug logging to the console. | | `enabled` | `boolean` | `true` | Whether the client connects to the bus at all. | | `reconnectEveryMs` | `number` | `300` | Interval (ms) between connection retry attempts. | ## Event Maps and Type Safety The generic `EventMap` type maps event names to payload types. Keys are event suffixes only — the `pluginId` is prepended automatically by `EventClient` when emitting and listening: ```ts type MyEvents = { 'state-update': { count: number } 'action': { type: string } } ``` TypeScript enforces correct event names and payload shapes at compile time. You get autocomplete on event names and type errors if the payload does not match the declared shape. ## Emitting Events Call `eventClient.emit(eventSuffix, payload)` to dispatch an event. You pass only the **suffix** (the part after the colon). The `pluginId` is prepended automatically: ```ts // If pluginId is 'my-plugin' and event map has 'state-update' myEventClient.emit('state-update', { count: 42 }) // Dispatches event named 'my-plugin:state-update' ``` If the client is not yet connected to the bus, the event is queued and flushed once the connection succeeds (see [Connection Lifecycle](#connection-lifecycle) below). ## Listening to Events There are three methods for subscribing to events. Each returns a cleanup function you call to unsubscribe. ### `on(eventSuffix, callback)` Listen to a specific event from this plugin. Like `emit`, you pass only the suffix: ```ts const cleanup = myEventClient.on('state-update', (event) => { console.log(event.payload.count) // typed as { count: number } }) // Later: stop listening cleanup() ``` The callback receives the full event object: ```ts { type: 'my-plugin:state-update', // fully qualified event name payload: { count: number }, // typed payload pluginId: 'my-plugin' // originating plugin } ``` ### `onAll(callback)` Listen to **all** events from **all** plugins. Useful for logging, debugging, or building cross-plugin features: ```ts const cleanup = myEventClient.onAll((event) => { console.log(event.type, event.payload) }) ``` ### `onAllPluginEvents(callback)` Listen to all events from **this** plugin only (filtered by `pluginId`): ```ts const cleanup = myEventClient.onAllPluginEvents((event) => { // Only fires for events where event.pluginId === 'my-plugin' console.log(event.type, event.payload) }) ``` ## Connection Lifecycle The `EventClient` manages its connection to the event bus automatically: ```mermaid stateDiagram-v2 [*] --> Queueing: First emit() call Queueing --> Connecting: Dispatches tanstack-connect Connecting --> Retrying: No response Retrying --> Connecting: Every 300ms (up to 5×) Connecting --> Connected: tanstack-connect-success Connected --> Connected: Emit events directly Queueing --> Connected: Flush queued events Retrying --> Failed: 5 retries exhausted Failed --> [*]: Subsequent emits dropped ``` 1. **Queueing** — When you call `emit()` before the client is connected, events are queued in memory. 2. **Connection** — On the first `emit()`, the client dispatches a `tanstack-connect` event and starts a retry loop. 3. **Retries** — The client retries every `reconnectEveryMs` (default: 300ms) up to a maximum of 5 attempts. 4. **Flush** — Once a `tanstack-connect-success` event is received, all queued events are flushed to the bus in order. 5. **Failure** — If all 5 retries are exhausted without a successful connection, the client stops retrying. Subsequent `emit()` calls are silently dropped (they will not be queued). ### The `enabled` Option When `enabled` is set to `false`, the EventClient is effectively inert — `emit()` is a no-op and `on()` returns a no-op cleanup function. This is useful for conditionally disabling devtools instrumentation (e.g., in production). ## Server Event Bus When `connectToServerBus: true` is set in the component's `eventBusConfig` prop, the `ClientEventBus` connects to the `ServerEventBus` started by the Vite plugin (default port 4206). This enables server-side features like console piping and the plugin marketplace. ```tsx ``` Without the Vite plugin running, the `EventClient` still works for same-page communication between your application code and the devtools panel. The server bus is only needed for features that bridge the browser and the dev server. ## Debugging Set `debug: true` in the `EventClient` constructor or in `eventBusConfig` to enable verbose console logging. Debug logs are prefixed with `[tanstack-devtools:{pluginId}]` for plugin events and `[tanstack-devtools:client-bus]` for the client bus. ```ts const myEventClient = new MyEventClient() // In the constructor: super({ pluginId: 'my-plugin', debug: true }) ``` Example output: ``` 🌴 [tanstack-devtools:client-bus] Initializing client event bus 🌴 [tanstack-devtools:my-plugin] Registered event to bus my-plugin:state-update 🌴 [tanstack-devtools:my-plugin] Emitting event my-plugin:state-update ``` This is helpful when diagnosing issues with event delivery, connection timing, or verifying that your event map is wired up correctly.