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

quick-start-server.md

174 lines4.9 KB

1---
2title: "Quick Start: Server Only"
3id: quick-start-server
4order: 5
5description: "Add a streaming AI chat endpoint to a Node.js backend with TanStack AI — no UI framework required."
6keywords:
7 - tanstack ai
8 - node.js
9 - server
10 - backend
11 - quick start
12 - streaming chat
13 - openai
14 - sse
15---
16​
17You have a Node.js backend and want to add AI capabilities. By the end of this guide, you'll have a working chat endpoint powered by TanStack AI and OpenAI -- no UI framework required.
18​
19> **Tip:** If you'd prefer not to sign up with individual AI providers, [OpenRouter](../adapters/openrouter) gives you access to 300+ models with a single API key and is the easiest way to get started.
20​
21## Installation
22​
23```bash
24npm install @tanstack/ai @tanstack/ai-openai
25# or
26pnpm add @tanstack/ai @tanstack/ai-openai
27# or
28yarn add @tanstack/ai @tanstack/ai-openai
29```
30​
31## Basic Chat
32​
33The simplest way to get a response -- call `chat()` and collect the text:
34​
35```typescript
36import { chat, streamToText } from '@tanstack/ai'
37import { openaiText } from '@tanstack/ai-openai'
38​
39const stream = chat({
40 adapter: openaiText('gpt-4o'),
41 messages: [{ role: 'user', content: 'Hello!' }],
42})
43​
44const text = await streamToText(stream)
45console.log(text)
46```
47​
48`chat()` returns an `AsyncIterable<StreamChunk>`. `streamToText` consumes it and returns the accumulated text content.
49​
50## HTTP Endpoint
51​
52Here's an Express server that exposes a streaming chat endpoint using Server-Sent Events:
53​
54```typescript
55import express from 'express'
56import { chat, toServerSentEventsResponse } from '@tanstack/ai'
57import { openaiText } from '@tanstack/ai-openai'
58​
59const app = express()
60app.use(express.json())
61​
62app.post('/api/chat', async (req, res) => {
63 const { messages } = req.body
64​
65 const stream = chat({
66 adapter: openaiText('gpt-4o'),
67 messages,
68 })
69​
70 const response = toServerSentEventsResponse(stream)
71 res.writeHead(response.status, Object.fromEntries(response.headers))
72​
73 const body = response.body
74 if (body) {
75 const reader = body.getReader()
76 const pump = async () => {
77 const { done, value } = await reader.read()
78 if (done) {
79 res.end()
80 return
81 }
82 res.write(value)
83 await pump()
84 }
85 await pump()
86 }
87})
88​
89app.listen(3000, () => console.log('Server running on port 3000'))
90```
91​
92> **Tip:** Any backend that returns the TanStack AI SSE format works -- you can use Fastify, Hono, or any other Node.js framework.
93​
94This endpoint is compatible with TanStack AI's client-side `useChat` hooks (`@tanstack/ai-react`, `@tanstack/ai-vue`, `@tanstack/ai-svelte`), so you can pair it with any frontend later.
95​
96## With Tools
97​
98Define a server tool with `toolDefinition` and pass it to `chat()`. The agent loop automatically calls your tool and feeds the result back to the model:
99​
100```typescript
101import { chat, toolDefinition, streamToText } from '@tanstack/ai'
102import { openaiText } from '@tanstack/ai-openai'
103import { z } from 'zod'
104​
105const getWeather = toolDefinition({
106 name: 'getWeather',
107 description: 'Get weather for a city',
108 inputSchema: z.object({ city: z.string() }),
109 outputSchema: z.object({ temp: z.number(), condition: z.string() }),
110}).server(async ({ city }) => {
111 return { temp: 22, condition: 'sunny' }
112})
113​
114const stream = chat({
115 adapter: openaiText('gpt-4o'),
116 messages: [{ role: 'user', content: 'Weather in Tokyo?' }],
117 tools: [getWeather],
118})
119​
120const text = await streamToText(stream)
121console.log(text)
122```
123​
124The model decides when to call `getWeather`, receives the result, and incorporates it into its response -- all within a single `chat()` call.
125​
126## Alternative Response Formats
127​
128TanStack AI ships several ways to return a stream over HTTP:
129​
130**`toHttpResponse()`** returns a `Response` using newline-delimited JSON instead of SSE. Pair it with `fetchHttpStream` on the client:
131​
132```typescript
133import { chat, toHttpResponse } from '@tanstack/ai'
134import { openaiText } from '@tanstack/ai-openai'
135​
136const stream = chat({
137 adapter: openaiText('gpt-4o'),
138 messages,
139})
140const response = toHttpResponse(stream)
141```
142​
143**Raw stream consumption** -- iterate the `AsyncIterable` directly with `for await`:
144​
145```typescript
146for await (const chunk of stream) {
147 if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
148 process.stdout.write(chunk.delta ?? '')
149 }
151```
152​
153This gives you full control over every chunk type (text deltas, tool calls, run lifecycle events, etc.).
154​
155## Environment Variables
156​
157Create a `.env` file with your API key:
158​
159```bash
160# OpenRouter (recommended — access 300+ models with one key)
161OPENROUTER_API_KEY=sk-or-...
162​
163# OpenAI
164OPENAI_API_KEY=your-openai-api-key
165```
166​
167The adapter reads `OPENAI_API_KEY` at runtime. Never expose it to the browser.
168​
169## Next Steps
170​
171- Learn about [Tools](../tools/tools) to add function calling and agent loops
172- Explore [StreamProcessor](../reference/classes/StreamProcessor) for fine-grained stream control
173- Check out the [Adapters](../adapters/openai) to connect to different providers
174- See the [React Quick Start](./quick-start) to add a frontend