package
Web adapter for Chat SDK — browser chat UI over the AI SDK or AG-UI (TanStack AI) stream protocols
npm install @chat-adapter/webGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 24 packages.
2.4 MB
Includes dependencies.
vercel-release-bot
infra+release@vercel.com
Web adapter for Chat SDK. Lets a chat-sdk bot serve a browser chat UI alongside Slack, Teams, Discord, etc. — the same bot.onDirectMessage(...) handler fires for every platform.
The adapter speaks the AI SDK UI message stream protocol by default, so React, Vue, and Svelte AI SDK clients work against the server endpoint. Set protocol: "ag-ui" to speak AG-UI instead, for TanStack AI and other AG-UI clients. The server has no runtime dependency on either client SDK.
Documentation: chat-sdk.dev/adapters/official/web · Guides: vercel.com/kb/chat-sdk
pnpm add @chat-adapter/webThen install the client packages that match your UI:
| Client | Packages | Import from | protocol |
|---|---|---|---|
| AI SDK + React / Next.js | ai, @ai-sdk/react | @chat-adapter/web/react | "ai-sdk" (default) |
| AI SDK + Vue / Nuxt | ai, @ai-sdk/vue | @chat-adapter/web/vue | "ai-sdk" (default) |
| AI SDK + Svelte / SvelteKit | ai, @ai-sdk/svelte | @chat-adapter/web/svelte | "ai-sdk" (default) |
| TanStack AI | @tanstack/ai-react (or another TanStack AI framework package) | @tanstack/ai-react | "ag-ui" |
To scaffold a new browser chat bot with the Web adapter preselected:
npx create-chat-sdk@latest my-bot --adapter web memoryVisit the adapters directory to see other available official and vendor-official adapters.
// lib/bot.ts
import { Chat } from "chat";
import { createWebAdapter } from "@chat-adapter/web";
import { createMemoryState } from "@chat-adapter/state-memory";
export const bot = new Chat({
userName: "mybot",
adapters: {
web: createWebAdapter({
userName: "mybot",
getUser: (req) => ({ id: getUserIdFromCookie(req) }),
}),
},
state: createMemoryState(),
});
bot.onDirectMessage(async (thread, message) => {
await thread.post(`You said: ${message.text}`);
});// app/api/chat/route.ts
import { after } from "next/server";
import { bot } from "@/lib/bot";
export async function POST(request: Request): Promise<Response> {
return bot.webhooks.web(request, {
waitUntil: (task) => after(() => task),
});
}// app/chat/page.tsx
"use client";
import { useChat } from "@chat-adapter/web/react";
export default function ChatPage() {
const { messages, sendMessage, status, stop } = useChat();
// Render with `ai-elements` (<Conversation>, <Message>, <PromptInput>)
// or your own components — `messages`, `sendMessage`, `status` are the
// standard `@ai-sdk/react` API.
}<!-- components/Chat.vue -->
<script setup lang="ts">
import { useChat } from "@chat-adapter/web/vue";
const chat = useChat({ api: "/api/chat" });
</script>
<template>
<div v-for="msg in chat.messages" :key="msg.id">
<template
v-for="(part, index) in msg.parts"
:key="`${msg.id}-${part.type}-${index}`"
>
<p v-if="part.type === 'text'">{{ part.text }}</p>
</template>
</div>
</template><!-- Chat.svelte -->
<script lang="ts">
import { useChat } from "@chat-adapter/web/svelte";
const chat = useChat({ api: "/api/chat" });
</script>
{#each chat.messages as msg (msg.id)}
{#each msg.parts as part, index (`${msg.id}-${part.type}-${index}`)}
{#if part.type === "text"}<p>{part.text}</p>{/if}
{/each}
{/each}Set protocol: "ag-ui" on the adapter, then point TanStack AI's useChat at the route with fetchServerSentEvents:
createWebAdapter({
userName: "mybot",
getUser: (req) => ({ id: getUserIdFromCookie(req) }),
protocol: "ag-ui",
});// app/chat/page.tsx
"use client";
import { fetchServerSentEvents, useChat } from "@tanstack/ai-react";
export default function ChatPage() {
const { messages, sendMessage, isLoading, stop } = useChat({
connection: fetchServerSentEvents("/api/chat"),
threadId: "support-1",
});
// Text parts carry their text in `part.content`.
}threadId becomes the conversation id in the chat-sdk thread id. Each thread.post call arrives as its own assistant message, and handler errors end the run with a RUN_ERROR event.
getUser is the security boundary for the Web adapter. Unlike Slack/Teams where the platform signs every webhook, web requests come straight from a browser — you must identify the caller yourself. Returning null causes the adapter to respond with HTTP 401 and no handler runs.
Plug in whatever your app already uses:
// NextAuth
createWebAdapter({
userName: "mybot",
getUser: async (req) => {
const session = await getServerSession(authOptions);
if (!session?.user) return null;
return { id: session.user.id, name: session.user.name };
},
});
// Clerk
createWebAdapter({
userName: "mybot",
getUser: async (req) => {
const { userId, sessionClaims } = await auth();
if (!userId) return null;
return { id: userId, name: sessionClaims?.name as string | undefined };
},
});
// Custom session cookie
createWebAdapter({
userName: "mybot",
getUser: async (req) => {
const sessionId = req.headers.get("cookie")?.match(/session=([^;]+)/)?.[1];
if (!sessionId) return null;
const user = await db.users.findBySession(sessionId);
return user ? { id: user.id, name: user.name } : null;
},
});If getUser throws, the adapter returns 401 and logs the error. Don't include sensitive data in the error message — it's not surfaced to the client, but it is logged.
The resolved
user.idis embedded in the chat-sdk thread id (see Threading below). User ids containing:are rejected with HTTP 400 because they would corrupt the round-trip throughdecodeThreadId. If your auth provider emits ids with colons (e.g.provider:subclaims), normalize them insidegetUser— for example by base64-encoding.
By default, each useChat conversation maps to one chat-sdk thread:
web:{user.id}:{conversationId}conversationId is the id field AI SDK's useChat sends in its request body, or the threadId field with protocol: "ag-ui". If your client supplies one (useChat({ id: "support-chat" })), it's reused across reloads; otherwise a fresh id is generated per request. A conversation id that isn't a string, or that contains :, is rejected with HTTP 400.
channel.messages and thread.messages are equivalent on web — the channel id is the thread id. This avoids cross-conversation bleed when persistMessageHistory is enabled and the same user has multiple useChat conversations open.
To override (for example, one thread per user regardless of conversation):
createWebAdapter({
userName: "mybot",
getUser: (req) => /* ... */,
threadIdFor: ({ user }) => `web:${user.id}:default`,
});The encode/decode helpers are exposed on the adapter:
adapter.encodeThreadId({ userId: "u1", conversationId: "abc" });
// → "web:u1:abc"
adapter.decodeThreadId("web:u1:abc");
// → { userId: "u1", conversationId: "abc" }thread.post accepts an AsyncIterable<string | StreamChunk> and pumps deltas straight onto the SSE response body — no edit loop, no rate limiting. Handlers can use any model library. For example, with the AI SDK's streamText:
import { streamText } from "ai";
// Bring your own model from any AI SDK provider
// (@ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google, ...).
bot.onDirectMessage(async (thread, message) => {
const result = streamText({
model: myModel,
prompt: message.text,
});
await thread.post(result.textStream);
});The adapter honors request.signal, so calling stop() from the client short-circuits the iterator on the server.
With "ai-sdk", task_update and plan_update StreamChunks reach useChat as data-task and data-plan message parts, and reasoning chunks as reasoning parts. With "ag-ui", reasoning streams as REASONING_* events and task and plan updates as CUSTOM events named task and plan. See the Web adapter docs.
persistMessageHistory defaults to true. Web has no platform-side history API, so the only way for chat-sdk handlers to see prior turns via thread.messages / channel.messages is through the configured state adapter's message history cache. Set it to false only if your handler doesn't need prior turns:
createWebAdapter({
userName: "mybot",
getUser: (req) => /* ... */,
persistMessageHistory: false,
});The client resends the whole conversation on every request, but the adapter doesn't read history from it. A browser controls the request body's messages[] array, so the adapter consumes only the latest user message and strips tool parts from it. The last entry must be a user message; a body ending in an assistant or tool message, such as a client-side tool result, is rejected with HTTP 400. Sending the same user message again (regenerate() or a reload) runs the handler again rather than being dropped as a duplicate, and history keeps the earlier reply and stores the repeated message a second time.
message.raw is typed WebMessage. Part fields other than type are unknown. With "ai-sdk" the shape matches the AI SDK UIMessage, so you can cast it with message.raw as UIMessage.
@chat-adapter/web/react exports a thin wrapper around @ai-sdk/react's useChat preconfigured with DefaultChatTransport:
import { useChat } from "@chat-adapter/web/react";
const { messages, sendMessage, status, stop, regenerate } = useChat({
api: "/api/chat", // default
threadId: "support-1", // becomes useChat's `id` and the request body's `id`
});| Option | Description |
|---|---|
api | API endpoint for the Web adapter route. Defaults to /api/chat. |
threadId | chat-sdk thread id — surfaces in the request body's id so the server can derive the chat-sdk thread id. Strongly recommended. Falls back to id from ChatInit. |
experimental_throttle | Throttle wait in ms for chat messages and data updates. |
resume | Whether to resume an ongoing chat generation stream. |
| ...rest | All other options pass through to @ai-sdk/react's useChat. |
For advanced configuration (custom transport, response interceptors, etc.) use @ai-sdk/react's useChat directly — there's nothing magical in the wrapper.
@chat-adapter/web/vue exports a useChat factory that returns a Vue-reactive Chat instance from @ai-sdk/vue:
<script setup lang="ts">
import { useChat } from "@chat-adapter/web/vue";
const chat = useChat({ api: "/api/chat", threadId: "support-1" });
</script>
<template>
<div v-for="msg in chat.messages" :key="msg.id">
<template
v-for="(part, index) in msg.parts"
:key="`${msg.id}-${part.type}-${index}`"
>
<p v-if="part.type === 'text'">{{ part.text }}</p>
</template>
</div>
</template>@chat-adapter/web/svelte exports a useChat factory that returns a Svelte-reactive Chat instance from @ai-sdk/svelte:
<script lang="ts">
import { useChat } from "@chat-adapter/web/svelte";
const chat = useChat({ api: "/api/chat", threadId: "support-1" });
</script>
{#each chat.messages as msg (msg.id)}
{#each msg.parts as part, index (`${msg.id}-${part.type}-${index}`)}
{#if part.type === "text"}<p>{part.text}</p>{/if}
{/each}
{/each}Unlike the React helper, Vue and Svelte return the Chat instance directly. Access chat.messages, chat.sendMessage(), chat.status, and chat.stop() on that object instead of destructuring.
| Option | Required | Description |
|---|---|---|
userName | Yes | Bot username. Required by chat-sdk for mention detection (@username) and seeds the bot identity for assistant messages. |
getUser | Yes | (request: Request) => WebUser | null | Promise<WebUser | null>. Resolves the user from the inbound HTTP request. Returning null produces HTTP 401. |
protocol | No | "ai-sdk" (default) or "ag-ui". Wire protocol for requests and streamed responses. Use "ag-ui" for TanStack AI and other AG-UI clients. |
persistMessageHistory | No | Persist incoming message history in the configured state adapter. Default: true. |
threadIdFor | No | Derive a chat-sdk thread id from the resolved user and the useChat conversation id. Default: web:{user.id}:{conversationId}. |
logger | No | Logger instance (defaults to ConsoleLogger("info")). |
| Feature | Supported |
|---|---|
| Post message | Yes |
| Edit message | No (every assistant turn is a fresh streamed response) |
| Delete message | No |
| File uploads | No (deferred to v2) |
| Streaming | Native (SSE: AI SDK UI message stream or AG-UI) |
| Scheduled messages | No |
| Feature | Supported |
|---|---|
| Card format | Markdown only in v1 (cards/JSX deferred to v2) |
| Buttons | No |
| Tables | Yes (GFM markdown) |
| Modals | No |
| Feature | Supported |
|---|---|
| Mentions | N/A (every web message routes as a DM) |
| Add reactions | No |
| Remove reactions | No |
| Typing indicator | N/A (useChat derives a status from the SSE response itself) |
| DMs | Yes — isDM: true for every thread |
| Feature | Supported |
|---|---|
| Fetch messages | Via state adapter cache (no platform API) |
| Fetch single message | No |
| Fetch thread info | Yes (synthesized) |
| Fetch channel messages | Via state adapter cache |
| List threads | No |
| Post channel message | No |
In: text + markdown, native streaming, task and plan updates as data-* parts, reasoning parts, DM-style routing, persisted message history, abort propagation via request.signal.
Out (deferred to v2): cards/JSX rendering, reactions, modals, file uploads, edit/delete, multi-tab proactive push.
getUser is returning null or throwing. Add a log inside it to confirm the request actually carries the session you expect.useChat is mounted on the same origin as /api/chat (or that your transport passes credentials).getUser contains a : character, which would corrupt the thread-id round-trip. Normalize the id inside getUser (for example, id.replace(/:/g, "_") or base64-encode it).useChat recreates state on every renderid: undefined to useChat. The wrapper guards against this internally — but if you're calling @ai-sdk/react's useChat directly, omit id rather than passing undefined.thread.messages is emptypersistMessageHistory is false and there is no platform-side history to fall back on. Set it to true (the default). The adapter never passes the request body's messages[] to handlers, so the state adapter is the only source of prior turns.useChat's sendAutomaticallyWhen) send a body ending in an assistant or tool message, which isn't supported.If you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.
npx skills add vercel/chatThe skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.
You can also install the Vercel Plugin for a broader agent toolkit — it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:
npx plugins add vercel/vercel-pluginThe plugin is optional; the skill alone is enough to build with Chat SDK.
For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).
MIT
4.45.0
4.45.0