* docs: add documentation redesign design document Comprehensive plan for restructuring TanStack Devtools documentation with layered architecture approach: Getting Started, Concepts, Guides, API Reference, and Examples sections. Adds 11 new pages including architecture overview, event system deep-dive, Vue framework support, and plugin building guides. * docs: add documentation implementation plan 18-task plan covering: navigation restructure, 4 new Concepts pages (architecture, event system, plugin lifecycle, source inspector), 3 new Guides (custom plugins, devtools-utils, bidirectional comms), Vue framework support, Solid custom plugins, and updates to existing pages including overview, quick-start, installation, and React adapter. * docs: restructure navigation with Concepts and Guides sections, add Vue * docs: expand overview with package map and architecture diagram * docs: add all framework examples to quick start * docs: add Vue and Preact installation instructions * docs: add architecture overview page * docs: add event system concepts page * docs: add plugin lifecycle concepts page * docs: add source inspector concepts page * docs: add framework-agnostic custom plugin building guide * docs: add devtools-utils guide for plugin factory helpers * docs: add bidirectional communication guide * docs: add Vue basic setup and adapter pages * docs: add Vue and Solid custom plugins guides * docs: replace TODO in React adapter with actual content * docs: expand Vite plugin features documentation * docs: fix event map key convention, typos, and internal link extensions - Event map keys should be suffix-only (e.g., 'state-update'), not prefixed with pluginId. EventClient prepends pluginId automatically. Fixed across all custom plugin guides and concept pages. - Fix enabled:false docs in event-system.md (emit is a no-op, not internal dispatch) - Fix double "the the" typo in installation.md - Remove .md extensions from internal doc links for consistency - Fix event map key in configuration.md example * docs: remove internal plan files * docs: replace ASCII diagrams with mermaid in architecture overview * docs: add mermaid diagrams across all documentation pages - overview.md: architecture layer diagram - event-system.md: connection lifecycle state diagram - plugin-lifecycle.md: mount sequence flowchart + portal pattern diagram - source-inspector.md: inspection flow diagram - building-custom-plugins.md: plugin architecture overview - bidirectional-communication.md: two-way flow + time travel sequence diagram - vite-plugin.md: sub-plugin overview diagram
6.3 KiB
| title | id |
|---|---|
| Event System | 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:
import { EventClient } from '@tanstack/devtools-event-client'
type MyEvents = {
'state-update': { count: number }
'action': { type: string }
}
class MyEventClient extends EventClient<MyEvents> {
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:
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:
// 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 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:
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:
{
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:
const cleanup = myEventClient.onAll((event) => {
console.log(event.type, event.payload)
})
onAllPluginEvents(callback)
Listen to all events from this plugin only (filtered by pluginId):
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:
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
- Queueing — When you call
emit()before the client is connected, events are queued in memory. - Connection — On the first
emit(), the client dispatches atanstack-connectevent and starts a retry loop. - Retries — The client retries every
reconnectEveryMs(default: 300ms) up to a maximum of 5 attempts. - Flush — Once a
tanstack-connect-successevent is received, all queued events are flushed to the bus in order. - 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.
<TanStackDevtools
eventBusConfig={{
connectToServerBus: true,
debug: false,
port: 4206, // default
}}
/>
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.
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.