Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

client-integration.md

286 lines8.7 KB

1---
2title: Showing Code Mode in the UI
3id: code-mode-client-integration
4order: 2
5description: "Stream Code Mode execution events to your React app — console output, external calls, and results as they happen, via onCustomEvent."
6keywords:
7 - tanstack ai
8 - code mode
9 - react ui
10 - custom events
11 - onCustomEvent
12 - streaming ui
13 - execution progress
14---
15​
16You have [Code Mode](./code-mode) working on your server — the LLM writes and executes TypeScript, and you get results back. But your users see nothing while the sandbox runs. By the end of this guide, your React app will show real-time execution progress: console output, external function calls, and final results as they stream in.
17​
18## How events reach the client
19​
20When code runs inside the sandbox, Code Mode emits **custom events** through the AG-UI streaming protocol. These events travel alongside normal chat chunks (text, tool calls) and arrive in your client via the `onCustomEvent` callback.
21​
22The events emitted during each `execute_typescript` call:
23​
24| Event | When | Key fields |
25|-------|------|------------|
26| `code_mode:execution_started` | Sandbox begins executing | `timestamp`, `codeLength` |
27| `code_mode:console` | Each `console.log/error/warn/info` | `level`, `message`, `timestamp` |
28| `code_mode:external_call` | Before an `external_*` function runs | `function`, `args`, `timestamp` |
29| `code_mode:external_result` | After a successful `external_*` call | `function`, `result`, `duration` |
30| `code_mode:external_error` | When an `external_*` call fails | `function`, `error`, `duration` |
31​
32Every event includes a `toolCallId` that ties it to the specific `execute_typescript` tool call, so you can render events alongside the right message.
33​
34## Listening to events with useChat
35​
36Pass an `onCustomEvent` callback to `useChat`. The callback receives the event type, payload, and a context object with the `toolCallId`:
37​
38```tsx group=code-mode-client
39import { useCallback, useRef, useState } from "react";
40import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
41​
42interface VMEvent {
43 id: string;
44 eventType: string;
45 data: unknown;
46 timestamp: number;
48​
49export function CodeModeChat() {
50 const [toolCallEvents, setToolCallEvents] = useState<
51 Map<string, Array<VMEvent>>
52 >(new Map());
53 const eventIdCounter = useRef(0);
54​
55 const handleCustomEvent = useCallback(
56 (
57 eventType: string,
58 data: unknown,
59 context: { toolCallId?: string },
60 ) => {
61 const { toolCallId } = context;
62 if (!toolCallId) return;
63​
64 const event: VMEvent = {
65 id: `event-${eventIdCounter.current++}`,
66 eventType,
67 data,
68 timestamp: Date.now(),
69 };
70​
71 setToolCallEvents((prev) => {
72 const next = new Map(prev);
73 const events = next.get(toolCallId) || [];
74 next.set(toolCallId, [...events, event]);
75 return next;
76 });
77 },
78 [],
79 );
80​
81 const { messages, sendMessage, isLoading } = useChat({
82 connection: fetchServerSentEvents("/api/chat"),
83 onCustomEvent: handleCustomEvent,
84 });
85​
86 // Render messages with events — see next section
88```
89​
90Events are keyed by `toolCallId` so each `execute_typescript` call gets its own event timeline.
91​
92## Rendering execution progress
93​
94When rendering messages, check for `execute_typescript` tool calls and display their events:
95​
96```tsx group=code-mode-client
97function MessageList({
98 messages,
99 toolCallEvents,
100}: {
101 messages: Array<{ id: string; role: string; parts: Array<any> }>;
102 toolCallEvents: Map<string, Array<VMEvent>>;
103}) {
104 return (
105 <div>
106 {messages.map((message) => (
107 <div key={message.id}>
108 {message.parts.map((part) => {
109 if (part.type === "text") {
110 return <p key={part.id}>{part.content}</p>;
111 }
112​
113 if (
114 part.type === "tool-call" &&
115 part.name === "execute_typescript"
116 ) {
117 const events = toolCallEvents.get(part.id) || [];
118 const result = part.output;
119​
120 return (
121 <div key={part.id}>
122 <CodeExecutionPanel
123 code={part.input?.typescriptCode}
124 events={events}
125 result={result}
126 isRunning={!result}
127 />
128 </div>
129 );
130 }
131​
132 return null;
133 })}
134 </div>
135 ))}
136 </div>
137 );
139```
140​
141## Building an execution panel
142​
143Here's a complete `CodeExecutionPanel` component that shows the generated code, live event stream, and final result:
144​
145```tsx group=code-mode-client
146function CodeExecutionPanel({
147 code,
148 events,
149 result,
150 isRunning,
151}: {
152 code?: string;
153 events: Array<VMEvent>;
154 result?: { success: boolean; result?: unknown; logs?: string[]; error?: { message: string } };
155 isRunning: boolean;
156}) {
157 return (
158 <div className="border rounded-lg overflow-hidden my-2">
159 {/* Generated code */}
160 {code && (
161 <details open>
162 <summary className="px-3 py-2 bg-gray-100 font-mono text-sm cursor-pointer">
163 TypeScript code
164 </summary>
165 <pre className="p-3 text-sm overflow-x-auto bg-gray-50">
166 <code>{code}</code>
167 </pre>
168 </details>
169 )}
170​
171 {/* Live event stream */}
172 {events.length > 0 && (
173 <div className="border-t px-3 py-2">
174 <div className="text-xs font-semibold text-gray-500 mb-1">
175 Execution log
176 </div>
177 <div className="space-y-1 font-mono text-xs">
178 {events.map((event) => (
179 <EventLine key={event.id} event={event} />
180 ))}
181 {isRunning && (
182 <div className="text-blue-500 animate-pulse">Running...</div>
183 )}
184 </div>
185 </div>
186 )}
187​
188 {/* Final result */}
189 {result && (
190 <div
191 className={`border-t px-3 py-2 text-sm ${
192 result.success ? "bg-green-50" : "bg-red-50"
193 }`}
194 >
195 {result.error && (
196 <div className="text-red-700">Error: {result.error.message}</div>
197 )}
198 {result.logs && result.logs.length > 0 && (
199 <pre className="text-gray-600 text-xs mt-1">
200 {result.logs.join("\n")}
201 </pre>
202 )}
203 {result.success && result.result !== undefined && (
204 <pre className="text-green-800 text-xs mt-1">
205 {JSON.stringify(result.result, null, 2)}
206 </pre>
207 )}
208 </div>
209 )}
210 </div>
211 );
213​
214function isRecord(value: unknown): value is Record<string, unknown> {
215 return typeof value === "object" && value !== null;
217​
218function EventLine({ event }: { event: VMEvent }) {
219 if (!isRecord(event.data)) return null;
220 const data = event.data;
221​
222 switch (event.eventType) {
223 case "code_mode:console":
224 return (
225 <div
226 className={
227 data.level === "error"
228 ? "text-red-600"
229 : data.level === "warn"
230 ? "text-yellow-600"
231 : "text-gray-600"
232 }
233 >
234 [{String(data.level)}] {String(data.message)}
235 </div>
236 );
237​
238 case "code_mode:external_call":
239 return (
240 <div className="text-amber-600">
241 → {String(data.function)}(
242 {JSON.stringify(data.args)})
243 </div>
244 );
245​
246 case "code_mode:external_result":
247 return (
248 <div className="text-green-600">
249 ← {String(data.function)} ({String(data.duration)}ms)
250 </div>
251 );
252​
253 case "code_mode:external_error":
254 return (
255 <div className="text-red-600">
256 ✗ {String(data.function)}: {String(data.error)}
257 </div>
258 );
259​
260 case "code_mode:execution_started":
261 return <div className="text-cyan-600">▶ Execution started</div>;
262​
263 default:
264 return (
265 <div className="text-gray-400">
266 {event.eventType}: {JSON.stringify(data)}
267 </div>
268 );
269 }
271```
272​
273This gives you:
274- A collapsible code block showing the TypeScript the model wrote
275- A live event log showing console output, external function calls with arguments, results with durations, and errors
276- A status-colored result panel with logs and the return value
277​
278## Adapting for other frameworks
279​
280The `onCustomEvent` callback is available through `ChatClient` from `@tanstack/ai-client`, which all framework integrations use under the hood. In Solid, Vue, or Svelte, pass `onCustomEvent` in the same way you pass it to `useChat` in React — the callback signature is identical:
281​
282```typescript ignore
283(eventType: string, data: unknown, context: { toolCallId?: string }) => void
284```
285​
286See [Code Mode](./code-mode) for setting up the server side, and [Code Mode with Skills](./code-mode-with-skills) for adding persistent skill libraries.