Open History to see the last commit
1# TanStack AI Examples
2
3This directory contains comprehensive examples demonstrating TanStack AI across multiple languages and frameworks.
4
5## Quick Start
6
7Choose an example based on your use case:
8
9- **Want a full-stack TypeScript app?** → [TanStack Chat (ts-react-chat)](#tanstack-chat-ts-react-chat)
10- **Need a vanilla JS frontend?** → [Vanilla Chat](#vanilla-chat)
11- **Building a Python backend?** → [Python FastAPI Server](#python-fastapi-server)
12- **Building a PHP backend?** → [PHP Slim Framework Server](#php-slim-framework-server)
13- **Multi-User TypeScript chat app?** → [Group Chat (ts-group-chat)](#group-chat-ts-group-chat)
14
15## TypeScript Examples
16
17### TanStack Chat (ts-react-chat)
18
19A full-featured chat application built with the TanStack ecosystem.
20
21**Tech Stack:**
22
23- TanStack Start (full-stack React framework)
24- TanStack Router (type-safe routing)
25- TanStack Store (state management)
26- `@tanstack/ai` (AI backend)
27- `@tanstack/ai-react` (React hooks)
28- `@tanstack/ai-client` (headless client)
29
30**Features:**
31
32- ✅ Real-time streaming with OpenAI GPT-4o
33- ✅ Automatic tool execution loop
34- ✅ Rich markdown rendering
35- ✅ Conversation management
36- ✅ Modern UI with Tailwind CSS
37
38**Getting Started:**
39
40```bash
41cd examples/ts-react-chat
42pnpm install
43cp env.example .env
44# Edit .env and add your OPENAI_API_KEY
45pnpm start
46```
47
48📖 [Full Documentation](ts-react-chat/README.md)
49
50---
51
52### Group Chat (ts-group-chat)
53
54A real-time multi-user chat application with AI integration, demonstrating WebSocket-based communication and TanStack AI.
55
56**Tech Stack:**
57
58- TanStack Start (full-stack React framework)
59- TanStack Router (type-safe routing)
60- Cap'n Web RPC (bidirectional WebSocket RPC)
61- `@tanstack/ai` (AI backend)
62- `@tanstack/ai-anthropic` (Claude adapter)
63- `@tanstack/ai-client` (headless client)
64- `@tanstack/ai-react` (React hooks)
65
66**Features:**
67
68- ✅ Real-time multi-user chat with WebSocket
69- ✅ Online presence tracking
70- ✅ AI assistant (Claude) integration with queuing
71- ✅ Message broadcasting to all users
72- ✅ Modern chat UI (iMessage-style)
73- ✅ Username-based authentication (no registration)
74
75**Getting Started:**
76
77```bash
78cd examples/ts-group-chat
79pnpm install
80cp .env.example .env
81# Edit .env and add your ANTHROPIC_API_KEY
82pnpm dev
83```
84
85Open `http://localhost:4000` in multiple browser tabs to test multi-user functionality.
86
87**Key Concepts:**
88
89- **WebSocket RPC**: Uses Cap'n Web RPC for type-safe bidirectional communication
90- **AI Queuing**: Claude requests are queued and processed sequentially
91- **Real-time Updates**: Messages and online users update in real-time
92- **Message Broadcasting**: Server broadcasts messages to all connected clients
93
94📖 [Full Documentation](ts-group-chat/README.md)
95
96---
97
98### Vanilla Chat
99
100A framework-free chat application using pure JavaScript and `@tanstack/ai-client`. Works with both PHP and Python backends.
101
102**Tech Stack:**
103
104- Vanilla JavaScript (no frameworks!)
105- `@tanstack/ai-client` (headless client)
106- Vite (dev server)
107- Compatible with PHP Slim or Python FastAPI backends
108
109**Features:**
110
111- ✅ Pure vanilla JavaScript
112- ✅ Real-time streaming messages
113- ✅ Beautiful, responsive UI
114- ✅ No framework dependencies
115- ✅ Works with multiple backend languages
116
117**Getting Started:**
118
119**Option 1: With Python Backend**
120
121```bash
122# Start the Python backend first
123cd examples/python-fastapi
124python anthropic-server.py
125
126# Then start the frontend
127cd examples/vanilla-chat
128pnpm install
129pnpm start
130```
131
132**Option 2: With PHP Backend**
133
134```bash
135# Start the PHP backend and UI together
136cd examples/php-slim
137pnpm install
138composer install
139cp env.example .env
140# Edit .env and add your ANTHROPIC_API_KEY
141pnpm start
142```
143
144Open `http://localhost:3001` (UI) - connects to backend on port 8000
145
146📖 [Full Documentation](vanilla-chat/README.md)
147
148---
149
150## Python Examples
151
152### Python FastAPI Server
153
154A FastAPI server that streams AI responses in Server-Sent Events (SSE) format, compatible with TanStack AI clients.
155
156**Features:**
157
158- ✅ FastAPI with SSE streaming
159- ✅ Converts Anthropic/OpenAI events to `StreamChunk` format
160- ✅ Compatible with `@tanstack/ai-client`
161- ✅ Tool call support
162- ✅ Type-safe with Pydantic
163
164**Getting Started:**
165
166```bash
167cd examples/python-fastapi
168
169# Create virtual environment
170python3 -m venv venv
171source venv/bin/activate # On Windows: venv\Scripts\activate
172
173# Install dependencies
174pip install -r requirements.txt
175
176# Set up environment
177cp env.example .env
178# Edit .env and add your ANTHROPIC_API_KEY or OPENAI_API_KEY
179
180# Run the server
181python anthropic-server.py # or openai-server.py
182```
183
184**API Endpoints:**
185
186- `POST /chat` - Stream chat responses in SSE format
187- `GET /health` - Health check
188
189**Usage with TypeScript Client:**
190
191```typescript
192import { ChatClient, fetchServerSentEvents } from '@tanstack/ai-client'
193
194const client = new ChatClient({
195 connection: fetchServerSentEvents('http://localhost:8000/chat'),
196})
197
198await client.sendMessage('Hello!')
199```
200
201📖 [Full Documentation](python-fastapi/README.md)
202
203---
204
205## PHP Examples
206
207### PHP Slim Framework Server
208
209A PHP Slim Framework server that streams AI responses in SSE format, with support for both Anthropic and OpenAI.
210
211**Features:**
212
213- ✅ Slim Framework with SSE streaming
214- ✅ Converts Anthropic/OpenAI events to `StreamChunk` format
215- ✅ Compatible with `@tanstack/ai-client`
216- ✅ Tool call support
217- ✅ PHP 8.1+ with type safety
218
219**Getting Started:**
220
221```bash
222cd examples/php-slim
223
224# Install dependencies
225composer install
226
227# Set up environment
228cp env.example .env
229# Edit .env and add your ANTHROPIC_API_KEY and/or OPENAI_API_KEY
230
231# Run the server
232composer start-anthropic # Runs on port 8000
233# or
234composer start-openai # Runs on port 8001
235```
236
237**API Endpoints:**
238
239- `POST /chat` - Stream chat responses in SSE format
240- `GET /health` - Health check
241
242**Usage with TypeScript Client:**
243
244```typescript
245import { ChatClient, fetchServerSentEvents } from '@tanstack/ai-client'
246
247const client = new ChatClient({
248 connection: fetchServerSentEvents('http://localhost:8000/chat'),
249})
250
251await client.sendMessage('Hello!')
252```
253
254📖 [Full Documentation](php-slim/README.md)
255
256---
257
258## Architecture Patterns
259
260### Full-Stack TypeScript
261
262Use TanStack AI end-to-end in TypeScript:
263
264```
265Frontend (React)
266 ↓ (useChat hook)
267@tanstack/ai-react
268 ↓ (ChatClient)
269@tanstack/ai-client
270 ↓ (SSE/HTTP)
271Backend (TanStack Start API Route)
272 ↓ (chat() function)
273@tanstack/ai
274 ↓ (adapter)
275AI Provider (OpenAI/Anthropic/etc.)
276```
277
278**Example:** [TanStack Chat (ts-react-chat)](ts-react-chat/README.md)
279
280### Multi-Language Backend
281
282Use Python or PHP for the backend, TypeScript for the frontend:
283
284```
285Frontend (Vanilla JS/React/Vue/etc.)
286 ↓ (ChatClient)
287@tanstack/ai-client
288 ↓ (SSE/HTTP)
289Backend (Python FastAPI or PHP Slim)
290 ↓ (tanstack-ai or tanstack/ai)
291Stream Conversion & Message Formatting
292 ↓ (provider SDK)
293AI Provider (OpenAI/Anthropic/etc.)
294```
295
296**Examples:**
297
298- [Python FastAPI](python-fastapi/README.md) + [Vanilla Chat](vanilla-chat/README.md)
299- [PHP Slim](php-slim/README.md) + [Vanilla Chat](vanilla-chat/README.md)
300- [PHP Slim](php-slim/README.md) + any frontend with `@tanstack/ai-client`
301
302## Common Patterns
303
304### Server-Sent Events (SSE) Streaming
305
306All examples use SSE for real-time streaming:
307
308**Backend (TypeScript):**
309
310```typescript
311import { chat, toStreamResponse } from '@tanstack/ai'
312import { openaiText } from '@tanstack/ai-openai'
313
314const stream = chat({
315 adapter: openaiText(),
316 model: 'gpt-4o',
317 messages,
318})
319
320return toStreamResponse(stream)
321```
322
323**Backend (Python):**
324
325```python
326from tanstack_ai import StreamChunkConverter, format_sse_chunk
327
328async for event in anthropic_stream:
329 chunks = await converter.convert_event(event)
330 for chunk in chunks:
331 yield format_sse_chunk(chunk)
332```
333
334**Backend (PHP):**
335
336```php
337use TanStack\AI\StreamChunkConverter;
338use TanStack\AI\SSEFormatter;
339
340foreach ($anthropicStream as $event) {
341 $chunks = $converter->convertEvent($event);
342 foreach ($chunks as $chunk) {
343 echo SSEFormatter::formatChunk($chunk);
344 }
345}
346```
347
348**Frontend:**
349
350```typescript
351import { ChatClient, fetchServerSentEvents } from '@tanstack/ai-client'
352
353const client = new ChatClient({
354 connection: fetchServerSentEvents('/api/chat'),
355})
356```
357
358### Automatic Tool Execution
359
360The TypeScript backend (`@tanstack/ai`) automatically handles tool execution:
361
362```typescript
363import { chat, toolDefinition } from '@tanstack/ai'
364import { z } from 'zod'
365
366// Step 1: Define the tool schema
367const weatherToolDef = toolDefinition({
368 name: 'getWeather',
369 description: 'Get weather for a location',
370 inputSchema: z.object({
371 location: z.string().describe('The city and state, e.g. San Francisco, CA'),
372 }),
373 outputSchema: z.object({
374 temp: z.number(),
375 condition: z.string(),
376 }),
377})
378
379// Step 2: Create server implementation
380const weatherTool = weatherToolDef.server(async ({ location }) => {
381 // This is called automatically by the SDK
382 return { temp: 72, condition: 'sunny' }
383})
384
385const stream = chat({
386 adapter: openaiText(),
387 model: 'gpt-4o',
388 messages,
389 tools: [weatherTool], // SDK executes these automatically
390})
391```
392
393Clients receive:
394
395- `content` chunks - text from the model
396- `tool_call` chunks - when the model calls a tool
397- `tool_result` chunks - results from tool execution
398- `done` chunk - conversation complete
399
400---
401
402## Development Tips
403
404### Running Multiple Examples
405
406You can run backend and frontend examples together:
407
408```bash
409# Option 1: Python backend + Vanilla Chat frontend
410# Terminal 1: Start Python backend
411cd examples/python-fastapi
412python anthropic-server.py
413
414# Terminal 2: Start vanilla frontend
415cd examples/vanilla-chat
416pnpm start
417
418# Option 2: PHP backend + Vanilla Chat frontend (runs together)
419cd examples/php-slim
420pnpm start # Starts both PHP server and vanilla-chat UI
421
422# Option 3: Full-stack TypeScript
423cd examples/ts-react-chat
424pnpm start
425```
426
427### Environment Variables
428
429Each example has an `env.example` file. Copy it to `.env` and add your API keys:
430
431```bash
432# TypeScript examples
433OPENAI_API_KEY=sk-...
434ANTHROPIC_API_KEY=sk-ant-...
435
436# Python examples
437ANTHROPIC_API_KEY=sk-ant-...
438OPENAI_API_KEY=sk-...
439
440# PHP examples
441ANTHROPIC_API_KEY=sk-ant-...
442OPENAI_API_KEY=sk-...
443```
444
445### Building for Production
446
447**TypeScript:**
448
449```bash
450pnpm build
451```
452
453**Python:**
454
455```bash
456# Use a production ASGI server
457uvicorn anthropic-server:app --host 0.0.0.0 --port 8000
458```
459
460**PHP:**
461
462```bash
463# Use a production web server (Apache, Nginx, etc.)
464# See php-slim/README.md for deployment details
465```
466
467---
468
469## Contributing
470
471When adding new examples:
472
4731. **Create a README.md** with setup instructions
4742. **Add an env.example** file with required environment variables
4753. **Document the tech stack** and key features
4764. **Include usage examples** with code snippets
4775. **Update this README** to list your example
478
479---
480
481## Learn More
482
483- 📖 [Main README](../README.md) - Project overview
484- 📖 [Documentation](../docs/) - Comprehensive guides
485- 📖 [TypeScript Packages](../packages/typescript/) - Core libraries
486- 📖 [Python Package](../packages/python/tanstack-ai/) - Python utilities
487- 📖 [PHP Package](../packages/php/tanstack-ai/) - PHP utilities
488
489---
490
491Built with ❤️ by the TanStack community