examples
README.md
TanStack AI Examples#
This directory contains comprehensive examples demonstrating TanStack AI across multiple TypeScript frameworks.
Quick Start#
Choose an example based on your use case:
- Want the smallest React + Start chat? β Basic Chat
- Want an image from a prompt? β Generate Image
- Want a table that fills as JSON streams? β Streaming Structured Table
- Want typed ticket routing? β Evaluate
- Want a blog desk with three agents? β Subagents
- Want your own MCP server? β MCP server
- Want an agent in the terminal? β Harness CLI
- Want a signed MCP webhook? β MCP Events
- Want the model to use a web page? β Computer Use
- Want a full-stack TypeScript app? β TanStack Chat (ts-react-chat)
- Need a live world stream? β World generation (ts-react-media)
- Need a vanilla JS frontend? β Vanilla Chat
- Multi-User TypeScript chat app? β Group Chat (ts-group-chat)
- Polyglot AG-UI backends (Go/Rust/PHP/Zig/Bash/Python)? β AG-UI Polyglot Echo (ag-ui)
TypeScript Examples#
Basic Chat#
A slim TanStack Start chat. One provider (OpenRouter). You paste your own key.
Path: examples/react/basic-chat
Getting Started:
pnpm --filter basic-chat dev
Open http://localhost:3100. Paste an OpenRouter key. Send a message.
π Full Documentation
Generate Image#
A slim TanStack Start image app. One provider (OpenRouter). You paste your own key.
Path: examples/react/generate-image
Getting Started:
pnpm --filter generate-image dev
Open http://localhost:3100. Paste an OpenRouter key. Type a prompt. Click Generate.
π Full Documentation
Streaming Structured Table#
A slim TanStack Start app. One schema. chat({ outputSchema, stream: true }) fills a table as JSON streams in.
Path: examples/react/streaming-structured-table
Getting Started:
pnpm --filter streaming-structured-table dev
Open http://localhost:3100. Paste an OpenRouter key. Send Compare 6 JavaScript frameworks.
π Full Documentation
Subagents#
A slim TanStack Start chat. Three named agents: researcher, SEO, and writer. Jev picks the agents for each turn. Research and SEO run together, and the writer runs after them. The UI shows a nested card for each.
Path: examples/react/subagents
Getting Started:
pnpm --filter subagents dev
Open http://localhost:3100. Paste an OpenRouter key. Ask for research, SEO titles, or a draft.
π Full Documentation
Persisted subagents#
The blog desk from the subagents example, with a saved chat. A refresh keeps the messages and the cards. A refresh during a run continues that run.
Path: examples/react/subagents-persisted
Getting Started:
pnpm --filter subagents-persisted dev
Open http://localhost:3105. Paste an OpenRouter key. Send a prompt. Then refresh the page.
π Full Documentation
Evaluate#
A slim TanStack Start app. Paste a support ticket. The app shows queue, urgency, and refund.
Path: examples/react/evaluate
Getting Started:
pnpm --filter evaluate dev
Open http://localhost:3100. For a hosted provider, add its key in .env. For Ollaya, run ollaya serve and ollaya pull laya:latest. Pick a provider. Click Submit.
π Full Documentation
MCP server#
A slim TanStack Start app. One tool, one resource, and one prompt. The page calls that server.
Path: examples/react/mcp-server
Getting Started:
pnpm --filter mcp-server dev
Open http://localhost:3100. Click Call the server.
π Full Documentation
Harness CLI#
A notes assistant in the terminal. A harness with two tools, run by runCli, with a small Ink screen on the session view.
Path: examples/harness-cli
Getting Started:
OPENAI_API_KEY=sk-... pnpm --filter harness-cli-example start
Ask it to save a note. Press y to approve the write.
π Full Documentation
MCP Events#
A slim TanStack Start app. Subscribe to incident.created, then receive a signed webhook.
Path: examples/react/mcp-events
Getting Started:
pnpm --filter mcp-events dev
Open http://127.0.0.1:3101. Click Subscribe, then Emit incident.
π Full Documentation
Computer Use#
A slim TanStack Start app. The model opens tanstack.com in Chromium and finds the computer use docs. One provider (OpenAI). Each screenshot shows in the chat.
Path: examples/react/computer-use
Getting Started:
pnpm --filter computer-use exec playwright-core install chromium
pnpm --filter computer-use dev
Set OPENAI_API_KEY in .env.local. Open http://localhost:3100. Click Send.
π Full Documentation
TanStack Chat (ts-react-chat)#
A full-featured chat application built with the TanStack ecosystem.
Tech Stack:
- TanStack Start (full-stack React framework)
- TanStack Router (type-safe routing)
- TanStack Store (state management)
@tanstack/ai(AI backend)@tanstack/ai-react(React hooks)@tanstack/ai-client(headless client)
Features:
- β Real-time streaming with OpenAI GPT-4o
- β Automatic tool execution loop
- β Rich markdown rendering
- β Conversation management
- β Modern UI with Tailwind CSS
Getting Started:
cd examples/ts-react-chat
pnpm install
cp env.example .env
# Edit .env and add your OPENAI_API_KEY
pnpm start
π Full Documentation
Group Chat (ts-group-chat)#
A real-time multi-user chat application with AI integration, demonstrating WebSocket-based communication and TanStack AI.
Tech Stack:
- TanStack Start (full-stack React framework)
- TanStack Router (type-safe routing)
- Cap'n Web RPC (bidirectional WebSocket RPC)
@tanstack/ai(AI backend)@tanstack/ai-anthropic(Claude adapter)@tanstack/ai-client(headless client)@tanstack/ai-react(React hooks)
Features:
- β Real-time multi-user chat with WebSocket
- β Online presence tracking
- β AI assistant (Claude) integration with queuing
- β Message broadcasting to all users
- β Modern chat UI (iMessage-style)
- β Username-based authentication (no registration)
Getting Started:
cd examples/ts-group-chat
pnpm install
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY
pnpm dev
Open http://localhost:4000 in multiple browser tabs to test multi-user functionality.
Key Concepts:
- WebSocket RPC: Uses Cap'n Web RPC for type-safe bidirectional communication
- AI Queuing: Claude requests are queued and processed sequentially
- Real-time Updates: Messages and online users update in real-time
- Message Broadcasting: Server broadcasts messages to all connected clients
π Full Documentation
Reranking (ts-react-rerank)#
A single-page app that reorders a fixed set of support articles by relevance to a query, showing the original order and the reranked order side by side.
Tech Stack:
- TanStack Start (full-stack React framework)
@tanstack/ai(thererank()activity)@tanstack/ai-cohere(Cohere rerank adapter)@tanstack/ai-openrouter(OpenRouter rerank adapter)
Features:
- β
One
rerank()call, two providers behind a dropdown - β Object documents β the original typed object comes back on each result
- β Relevance scores and original position per document
- β
topNcontrol and search-unit usage reporting - β API keys stay on the server
Getting Started:
cd examples/ts-react-rerank
pnpm install
cp .env.example .env
# Add COHERE_API_KEY and/or OPENROUTER_API_KEY β you only need the one you pick
pnpm dev
π Full Documentation
World generation (ts-react-media)#
The media example has a World tab. Pick a Reactor model for a live steerable stream, or a Marble model for a finished 3D World Labs world.
cd examples/ts-react-media
pnpm install
pnpm dev
Open the World tab. Paste a Reactor key (REACTOR_API_KEY) or a World Labs
key (WORLDLABS_API_KEY).
Vanilla Chat#
A framework-free chat application using pure JavaScript and @tanstack/ai-client.
Tech Stack:
- Vanilla JavaScript (no frameworks!)
@tanstack/ai-client(headless client)- Vite (dev server)
Features:
- β Pure vanilla JavaScript
- β Real-time streaming messages
- β Beautiful, responsive UI
- β No framework dependencies
Getting Started:
cd examples/vanilla-chat
pnpm install
pnpm start
π Full Documentation
AG-UI Polyglot Echo (ag-ui)#
A React SPA that connects to Go, Rust, PHP, Zig, Bash, and Python chat servers over the AG-UI SSE protocol, with each backend streaming OpenAI or Anthropic completions. Toolchain detection writes public/servers.json; unavailable backends show setup instructions in the UI.
Tech Stack:
- React + Vite (SPA)
@tanstack/ai-react+@tanstack/ai-react/ui- Go chat server (
net/http,:8001) - Rust chat server (Axum,
:8002) - PHP chat server (built-in server + curl,
:8003) - Zig chat server (stdlib HTTP,
:8004) - Bash chat server (socat + curl + jq,
:8005) - Python chat server (stdlib HTTP + urllib,
:8006)
Features:
- β Backend picker (Go | Rust | PHP | Zig | Bash | Python)
- β
Toolchain-gated
dev:all+servers.jsonavailability - β
Setup instructions when a runtime is missing (or disabled via
AGUI_DISABLE_SERVERS) - β Provider picker (OpenAI | Anthropic)
- β Hand-rolled AG-UI SSE in six languages
- β Streaming LLM responses via env API keys
Getting Started:
cd examples/ag-ui
pnpm install
cp .env.example .env
pnpm dev:all
Install whichever backends you want to run locally (Go, Rust, PHP, Zig, Bash, Python) plus provider API keys. The Bash server uses Bash 4+, curl, jq, and socat (brew install bash jq socat). To simulate missing runtimes: AGUI_DISABLE_SERVERS=php,zig,bash,python pnpm dev:all.
π Full Documentation
Architecture Patterns#
Full-Stack TypeScript#
Use TanStack AI end-to-end in TypeScript:
Frontend (React)
β (useChat hook)
@tanstack/ai-react
β (ChatClient)
@tanstack/ai-client
β (SSE/HTTP)
Backend (TanStack Start API Route)
β (chat() function)
@tanstack/ai
β (adapter)
AI Provider (OpenAI/Anthropic/etc.)
Example: TanStack Chat (ts-react-chat)
Common Patterns#
Server-Sent Events (SSE) Streaming#
All examples use SSE for real-time streaming:
Backend:
import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
const stream = chat({
adapter: openaiText(),
model: 'gpt-4o',
messages,
})
return toServerSentEventsResponse(stream)
Frontend:
import { ChatClient, fetchServerSentEvents } from '@tanstack/ai-client'
const client = new ChatClient({
connection: fetchServerSentEvents('/api/chat'),
})
Automatic Tool Execution#
The TypeScript backend (@tanstack/ai) automatically handles tool execution:
import { chat, toolDefinition } from '@tanstack/ai'
import { z } from 'zod'
// Step 1: Define the tool schema
const weatherToolDef = toolDefinition({
name: 'getWeather',
description: 'Get weather for a location',
inputSchema: z.object({
location: z.string().describe('The city and state, e.g. San Francisco, CA'),
}),
outputSchema: z.object({
temp: z.number(),
condition: z.string(),
}),
})
// Step 2: Create server implementation
const weatherTool = weatherToolDef.server(async ({ location }) => {
// This is called automatically by the SDK
return { temp: 72, condition: 'sunny' }
})
const stream = chat({
adapter: openaiText(),
model: 'gpt-4o',
messages,
tools: [weatherTool], // SDK executes these automatically
})
Clients receive:
contentchunks - text from the modeltool_callchunks - when the model calls a tooltool_resultchunks - results from tool executiondonechunk - conversation complete
Development Tips#
Environment Variables#
Each example has an env.example file. Copy it to .env and add your API keys:
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
Building for Production#
pnpm build
Contributing#
When adding new examples:
- Create a README.md with setup instructions
- Add an env.example file with required environment variables
- Document the tech stack and key features
- Include usage examples with code snippets
- Update this README to list your example
Learn More#
- π Main README - Project overview
- π Documentation - Comprehensive guides
- π TypeScript Packages - Core libraries
Built with β€οΈ by the TanStack community