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

quick-start.md

261 lines6.6 KB

1---
2title: Quick Start
3id: quick-start
4order: 2
5---
6​
7Get started with TanStack AI in minutes. This guide will walk you through creating a simple chat application using the React integration and OpenAI adapter.
8​
9## Installation
10​
11```bash
12npm install @tanstack/ai @tanstack/ai-react @tanstack/ai-openai
13# or
14pnpm add @tanstack/ai @tanstack/ai-react @tanstack/ai-openai
15#or
16yarn add @tanstack/ai @tanstack/ai-react @tanstack/ai-openai
17```
18​
19## Server Setup
20​
21First, create an API route that handles chat requests. Here's a simplified example:
22​
23### TanStack Start
24​
25```typescript
26import { chat, toStreamResponse } from "@tanstack/ai";
27import { openai } from "@tanstack/ai-openai";
28import { createFileRoute } from "@tanstack/react-router";
29​
30export const Route = createFileRoute("/api/chat")({
31 server: {
32 handlers: {
33 POST: async ({ request }) => {
34 // Check for API key
35 if (!process.env.OPENAI_API_KEY) {
36 return new Response(
37 JSON.stringify({
38 error: "OPENAI_API_KEY not configured",
39 }),
40 {
41 status: 500,
42 headers: { "Content-Type": "application/json" },
43 },
44 );
45 }
46​
47 const { messages, conversationId } = await request.json();
48​
49 try {
50 // Create a streaming chat response
51 const stream = chat({
52 adapter: openai(),
53 messages,
54 model: "gpt-4o",
55 conversationId,
56 });
57​
58 // Convert stream to HTTP response
59 return toStreamResponse(stream);
60 } catch (error) {
61 return new Response(
62 JSON.stringify({
63 error:
64 error instanceof Error ? error.message : "An error occurred",
65 }),
66 {
67 status: 500,
68 headers: { "Content-Type": "application/json" },
69 },
70 );
71 }
72 },
73 },
74 },
75});
76```
77​
78### Next.js
79​
80```typescript
81import { chat, toStreamResponse } from "@tanstack/ai";
82import { openaiText } from "@tanstack/ai-openai";
83​
84export async function POST(request: Request) {
85 // Check for API key
86 if (!process.env.OPENAI_API_KEY) {
87 return new Response(
88 JSON.stringify({
89 error: "OPENAI_API_KEY not configured",
90 }),
91 {
92 status: 500,
93 headers: { "Content-Type": "application/json" },
94 }
95 );
96 }
97​
98 const { messages, conversationId } = await request.json();
99​
100 try {
101 // Create a streaming chat response
102 const stream = chat({
103 adapter: openaiText("gpt-4o"),
104 messages,
105 conversationId
106 });
107​
108 // Convert stream to HTTP response
109 return toStreamResponse(stream);
110 } catch (error) {
111 return new Response(
112 JSON.stringify({
113 error: error instanceof Error ? error.message : "An error occurred",
114 }),
115 {
116 status: 500,
117 headers: { "Content-Type": "application/json" },
118 }
119 );
120 }
122```
123​
124## Client Setup
125​
126To use the chat API from your React frontend, create a `Chat` component:
127​
128```typescript
129// components/Chat.tsx
130import { useState } from "react";
131import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
132​
133export function Chat() {
134 const [input, setInput] = useState("");
135​
136 const { messages, sendMessage, isLoading } = useChat({
137 connection: fetchServerSentEvents("/api/chat"),
138 });
139​
140 const handleSubmit = (e: React.FormEvent) => {
141 e.preventDefault();
142 if (input.trim() && !isLoading) {
143 sendMessage(input);
144 setInput("");
145 }
146 };
147​
148 return (
149 <div className="flex flex-col h-screen">
150 {/* Messages */}
151 <div className="flex-1 overflow-y-auto p-4">
152 {messages.map((message) => (
153 <div
154 key={message.id}
155 className={`mb-4 ${
156 message.role === "assistant" ? "text-blue-600" : "text-gray-800"
157 }`}
158 >
159 <div className="font-semibold mb-1">
160 {message.role === "assistant" ? "Assistant" : "You"}
161 </div>
162 <div>
163 {message.parts.map((part, idx) => {
164 if (part.type === "thinking") {
165 return (
166 <div
167 key={idx}
168 className="text-sm text-gray-500 italic mb-2"
169 >
170 💭 Thinking: {part.content}
171 </div>
172 );
173 }
174 if (part.type === "text") {
175 return <div key={idx}>{part.content}</div>;
176 }
177 return null;
178 })}
179 </div>
180 </div>
181 ))}
182 </div>
183​
184 {/* Input */}
185 <form onSubmit={handleSubmit} className="p-4 border-t">
186 <div className="flex gap-2">
187 <input
188 type="text"
189 value={input}
190 onChange={(e) => setInput(e.target.value)}
191 placeholder="Type a message..."
192 className="flex-1 px-4 py-2 border rounded-lg"
193 disabled={isLoading}
194 />
195 <button
196 type="submit"
197 disabled={!input.trim() || isLoading}
198 className="px-6 py-2 bg-blue-600 text-white rounded-lg disabled:opacity-50"
199 >
200 Send
201 </button>
202 </div>
203 </form>
204 </div>
205 );
207```
208​
209## Environment Variables
210​
211To connect to AI providers, set your API keys in your environment variables. Create a `.env.local` file (or `.env` depending on your setup):
212```bash
213# OpenAI
214OPENAI_API_KEY=your-openai-api-key
215​
216# Anthropic
217ANTHROPIC_API_KEY=your-anthropic-api-key
218​
219# Google Gemini
220GEMINI_API_KEY=your-gemini-api-key
221```
222​
223## That's It!
224​
225You now have a working chat application. The `useChat` hook handles:
226​
227- Message state management
228- Streaming responses
229- Loading states
230- Error handling
231​
232## Using Tools
233​
234Since TanStack AI is framework-agnostic, you can define and use tools in any environment. Here's a quick example of defining a tool and using it in a chat:
235​
236```typescript
237import { chat } from '@tanstack/ai'
238import { toolDefinition } from '@tanstack/ai'
239import { openaiText } from '@tanstack/ai-openai'
240​
241const getProductsDef = toolDefinition({
242 name: 'getProducts',
243 inputSchema: z.object({ query: z.string() }),
244})
245​
246const getProducts = getProductsDef.server(async ({ query }) => {
247 return await db.products.search(query)
248})
249​
250chat({
251 adapter: openaiText('gpt-4o'),
252 messages: [{ role: 'user', content: 'Find products' }],
253 tools: [getProducts]
254})
255```
256​
257## Next Steps
258​
259- Learn about [Tools](../guides/tools) to add function calling
260- Check out [Client Tools](../guides/client-tools) for frontend operations
261- See the [API Reference](../api/ai) for more options