Open History to see the last commit
1---
2title: Devtools
3id: devtools
4order: 3
5description: "Inspect and debug TanStack AI apps with the TanStack Devtools panel — live chat messages, tool call inputs and outputs, state, and errors."
6keywords:
7 - tanstack ai
8 - devtools
9 - debugging
10 - tool inspection
11 - chat inspector
12 - react devtools
13 - observability
14---
15
16TanStack Devtools is a unified devtools panel for inspecting and debugging TanStack libraries, including TanStack AI. It provides real-time insights into AI interactions, tool calls, and state changes, making it easier to develop and troubleshoot AI-powered applications.
17
18## Features
19- **Hook dashboard** - Discover every active TanStack AI hook on the page, including chat, structured output, image, video, audio, speech, transcription, and summarize hooks.
20- **Run timeline** - Inspect user turns, linked runs, stream events, client snapshots, and server-only events by `threadId` and `runId`.
21- **Real-time Monitoring** - View live chat messages, tool invocations, and AI responses.
22- **Tool Call Inspection** - Inspect input and output of tool calls.
23- **Tool Fixture Replay** - Build tool payloads from a tool's standard-schema input, append the result into chat messages, and save fixtures in localStorage for repeated UI iteration.
24- **State Visualization** - Visualize chat state and message history.
25- **Memory Inspector** - For chats wired with `memoryMiddleware`, see what memory recalled and injected each turn plus the current stored records and facts.
26- **Error Tracking** - Monitor errors and exceptions in AI interactions.
27
28## Hook Dashboard
29
30The AI devtools panel listens for active TanStack AI clients and shows them in the left sidebar. Hooks register when they are created, emit a snapshot immediately, and respond again whenever the devtools panel opens or requests state. This keeps hooks discoverable even when the panel is opened after the app has already rendered.
31
32Each hook entry includes its type, lifecycle, message count, run count, and the latest linked `threadId`. Selecting a hook opens the full timeline for that hook. Chat hooks keep the current turn-based view: a user message wraps every run and event that happened while answering that turn. The details view also includes lightweight client/server state snapshots between runs so you can see exactly what changed.
33
34### Naming Hooks
35
36When a page has more than one AI hook, pass `devtools.name` to give each hook a user-facing label in the dashboard. The configured name is display-only; hook type, framework, thread id, and run correlation still come from the TanStack AI client.
37
38```tsx
39import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
40
41export function SupportChat() {
42 const chat = useChat({
43 threadId: 'support-chat',
44 connection: fetchServerSentEvents('/api/chat'),
45 devtools: {
46 name: 'Support Chat',
47 },
48 })
49
50 // render your chat UI with `chat.messages`, `chat.sendMessage`, etc.
51}
52```
53
54The same display option works for specialized generation hooks:
55
56```tsx
57import { fetchServerSentEvents, useGenerateImage } from '@tanstack/ai-react'
58
59export function ImageStudio() {
60 const image = useGenerateImage({
61 id: 'generation-hooks:useGenerateImage',
62 connection: fetchServerSentEvents('/api/image'),
63 devtools: {
64 name: 'Image Studio',
65 },
66 })
67
68 // render your image generation UI with `image.generate` and `image.result`
69}
70```
71
72## Tool Fixtures
73
74When a `useChat` hook receives tools, the devtools panel lists those tools and their schemas. For standard-schema-compatible inputs, the panel renders a small form from the input schema so you can create a tool call payload without hand-writing JSON.
75
76Applying a tool fixture appends the tool call and result into the real chat messages for that hook. Saved fixtures are stored in browser localStorage under the AI devtools namespace so they are available the next time you open the panel.
77
78## Memory Inspector
79
80When a chat is wired with [`memoryMiddleware`](../memory/overview.md), the hook's **Memory** tab shows what the server-side memory backend did for that conversation, grouped by scope (session):
81
82- **Operations timeline** - Each turn's recall: the query, how many fragments came back, how many characters were injected into the system prompt, whether memory-provided tools were exposed, and the recall duration.
83- **Stored records & facts** - The current contents of the memory store for the scope, when the adapter implements the optional `inspect`/`listFacts` methods (the built-in `inMemory()` and `redis()` adapters do). Adapters without introspection still show the operations timeline.
84
85Because memory runs on the server, its state is transported to the panel over the chat stream (a `CUSTOM` event the client re-emits) rather than a separate channel — the same way generation results reach the panel. The snapshot reflects memory as of the start of each turn, so a turn's own writes appear in the next turn's snapshot. Opening the panel after a turn replays the latest memory state, so the tab is populated even when you open devtools mid-conversation.
86
87## Event Sources
88
89Client-visible state is emitted by the headless client. Server-only details, such as middleware and provider stream events that never exist on the client, are emitted from the server counterpart. Events include a source descriptor and stable envelope id so the panel can link related events and avoid displaying duplicates.
90
91## Installation
92To use TanStack Devtools with TanStack AI, install the `@tanstack/react-ai-devtools` package:
93
94```bash
95npm install -D @tanstack/react-ai-devtools @tanstack/react-devtools
96```
97
98Or the `@tanstack/solid-ai-devtools` package for SolidJS:
99```bash
100npm install -D @tanstack/solid-ai-devtools @tanstack/solid-devtools
101```
102
103Or the `@tanstack/preact-ai-devtools` package for Preact:
104```bash
105npm install -D @tanstack/preact-ai-devtools @tanstack/preact-devtools
106```
107
108## Usage
109
110Import and include the TanStackDevtools component in your application:
111
112```tsx
113import { TanStackDevtools } from '@tanstack/react-devtools'
114import { aiDevtoolsPlugin } from '@tanstack/react-ai-devtools'
115
116const App = () => {
117 return (
118 <>
119 <TanStackDevtools
120 plugins={[
121 // ... other plugins
122 aiDevtoolsPlugin(),
123 ]}
124 // this config is important to connect to the server event bus
125 eventBusConfig={{
126 connectToServerBus: true,
127 }}
128 />
129 </>
130 )
131}
132```
133
134## Using with Next.js (or without a Vite plugin)
135
136`connectToServerBus: true` relies on a WebSocket/SSE server on port 4206 that is normally started by `@tanstack/devtools-vite`. If you're using Next.js (or any non-Vite bundler), you need to start `ServerEventBus` manually at server boot.
137
138In Next.js, do this in `instrumentation.ts`:
139
140```ts ignore
141export async function register() {
142 if (
143 process.env["NEXT_RUNTIME"] === "nodejs" &&
144 process.env.NODE_ENV === "development"
145 ) {
146 const { ServerEventBus } = await import(
147 "@tanstack/devtools-event-bus/server"
148 );
149 const bus = new ServerEventBus();
150 await bus.start();
151 }
152}
153```
154
155This sets globalThis.__TANSTACK_EVENT_TARGET__ so the server-side devtoolsMiddleware (which runs automatically inside every chat() call) can emit tool call events to the bus, which then forwards them to the devtools panel.