nextjs-chatbot

Next.js Chatbot

Opinionated blueprint for production web chatbots. Focuses on patterns not covered by /ai-sdk-7, /ai-elements, or /nextjs-shadcn — use those skills for general SDK, component, and framework questions. For multi-platform bots (Slack, Teams, Discord), use /vercel:chat-sdk instead.

Stack defaults

• Runtime: bun
• Model: a non-reasoning flagship with reasoning effort off — chat latency is the product. Read the version from the provider's live catalog, not from here.
• AI SDK: ai@7 — ToolLoopAgent, createAgentUIStreamResponse. ⚠️ Check package.json — on a v6 codebase the names below are wrong; see If the project is still on ai@6.
• UI: shadcn/ui (Base UI base) + ai-elements (see /ai-elements for component docs)
• Scroll: @shadcn/react MessageScroller — don't hand-roll stick-to-bottom
• Markdown: shadcn typeset (typeset typeset-chat), streaming-stable
• ORM: Drizzle + PostgreSQL
• State: Zustand for client-side chat state (consent, session, suggestions)
• Attachments: See /ai-elements Attachments component for file upload

Recommended MCP servers

• next-devtools (next-devtools-mcp@latest via npx) — route inspection, build diagnostics. See nextjs.org/docs/app/guides/mcp
• ai-elements (via mcp-remote → https://registry.ai-sdk.dev/api/mcp) — component registry search

Add both to the project's .mcp.json (claude mcp add writes it for you); .claude/settings.json only enables and permits servers, it does not define them.

Agent setup

export function createAgent(opts?: { model?: LanguageModel }) {
  return new ToolLoopAgent({
    model: opts?.model ?? openai(CHAT_MODEL), // one constant, read from env
    instructions,                             // NOT `system` — that is v6
    reasoning: "low",                         // portable top-level, see below
    tools,
    stopWhen: isStepCount(10),
  });
}
export const agent = createAgent();
export type AgentUIMessage = InferAgentUIMessage<typeof agent>;

Export both factory and singleton — factory needed for benchmarks. Wrap with devToolsMiddleware() in dev.

⚠️ Reasoning effort is the portable top-level reasoning, not providerOptions.openai.reasoningEffort — set both and the top-level one is silently ignored, so your setting does nothing. Raising it above "low" means keeping sendReasoning: false on the stream: the Responses API rejects a reasoning part that comes back on the next turn without its required follower, and a context trimmer that strips step-start/tool-* usually doesn't strip this one.

Route handler

export const maxDuration = 60;

export async function POST(request: Request) {
  const { messages, chatId, ...consent } = await request.json();
  // 1. Validate consent — return 403 if missing
  // 2. Await session upsert BEFORE streaming (FK dependency)
  return createAgentUIStreamResponse({
    agent,
    uiMessages: messages,
    generateMessageId: createIdGenerator({ prefix: "msg", size: 16 }),
    consumeSseStream: ({ stream }) => consumeStream({ stream }),
    experimental_transform: smoothStream({ delayInMs: 15, chunking: "word" }),
    sendReasoning: false,
    onEnd: async ({ responseMessage }) => { /* save — see persistence.md */ },
  });
}

Azure OpenAI model routing

Azure's Responses API does support non-reasoning models (gpt-4o), but multi-turn tool calls hit an intermittent 400 Item with id 'fc_...' not found error (Microsoft Q&A). Workaround: route non-reasoning models to Chat Completions (azure.chat()); reasoning models (gpt-5.x, o-series) use Responses API (default):

const isReasoning = /^(o[1-9]|gpt-5)/.test(deployment);
export const chatModel = isReasoning ? azure(deployment) : azure.chat(deployment);

Set reasoning only for reasoning models to avoid warnings.

If the project is still on ai@6

Everything on this page is patterns, not API surface, so it carries over — but the snippets above are v7 names and v6 doesn't know them. Some fail loudly (an undefined import); the dangerous ones fail quietly — a callback that never fires or a step limit that never applies, which reads as a model bug rather than a typo. Check package.json and translate back:

Use /ai-sdk-6 for the rest; /ai-sdk if you don't know the version yet.

Never let raw error text reach the browser

onError streams its return value verbatim to the client. String(error) there puts a provider 401, an endpoint URL or a Postgres constraint on a customer's screen — and logs nothing, so you find out from a screenshot.

onError: (error) => {          // log the real thing, return a sentence
  console.error("[chat]", error);
  return "Something went wrong generating the answer. Try again.";
}

The client needs the same guard separately: a non-2xx response never goes through the stream, so useChat's onError receives an Error whose message is the raw response body. Map it to a fixed set of sentences before rendering.

Custom streams need X-Accel-Buffering: no

Only for responses you build yourself — NDJSON upload progress, an SSE grid fill. createAgentUIStreamResponse already sets it. Without the header a buffering proxy (nginx, Cloud Run) holds the whole stream and delivers the progress bar in one jump at the end, which is worse than having no progress bar. Pair it with Cache-Control: no-store, no-transform.

⚠️ An error emitted inside an already-open stream arrives with HTTP 200 — the status is long gone. Rejections that happen before the stream opens do use real codes. Client code has to handle both shapes.

Client transport patterns

Dynamic context via transport body

Inject per-request context (e.g., a saved document for edit mode) from the client:

// Simple: body function on DefaultChatTransport
const transport = new DefaultChatTransport({
  api: "/api/chat",
  body: () => ({ documentContext: activeDocRef.current }),
});

// Fine-grained: prepareSendMessagesRequest (official API)
const transport = new DefaultChatTransport({
  prepareSendMessagesRequest: ({ id, messages }) => ({
    body: { id, message: messages.at(-1), context: extraRef.current },
  }),
});

Server reads extra fields from the request body and passes to agent factory.

Chat remount (new conversation)

Always call stop() before clearing — otherwise the active stream writes into the new conversation:

const { messages, sendMessage, stop, setMessages } = useChat({ transport });

const startNew = useCallback(() => {
  stop();                     // Cancel active stream FIRST
  setMessages([]);
  clearStoredMessages();      // If using localStorage
  setChatId(crypto.randomUUID());
  setConversationKey(k => k + 1);
}, [stop, setMessages]);

localStorage persistence (no DB)

For lightweight chatbots that don't need server-side persistence:

// Load on init via messages prop (NOT useEffect + setMessages)
const initialMessages = useMemo(() => {
  const stored = loadStoredMessages();
  return stored?.length ? (stored as UIMessage[]) : undefined;
}, []);

const { messages, sendMessage } = useChat({
  transport,
  messages: initialMessages,    // useChat accepts initial messages
  onFinish: ({ messages: all }) => saveStoredMessages(all),
});

Hydration: Zustand + localStorage

Zustand stores that read localStorage in create() cause React hydration mismatch (server: false, client: true). Fix with a mounted gate:

const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);

// In render:
{!mounted || !hasConsented ? <ConsentGate /> : <Chat />}

Same class of bug, different cause: relative timestamps ("6 seconds ago") on a server-rendered history list. The server and the client compute a different string, React calls it a mismatch and throws the whole subtree away to re-render it. Either render an absolute, locale-independent date, or gate the relative one behind the same mounted flag.

Adding a new tool

1. Create lib/ai/tools/my-tool.ts with tool() from ai
2. Export from lib/ai/tools/index.ts
3. Add to tools object in the agent file
4. Document in the agent's instructions string
5. Add UI renderer in chat-message.tsx (handle tool-myTool part type)

Structured output tools (schema-as-output)

When the tool generates structured data (not query/compute), use the pass-through pattern — the Zod schema defines the output, execute just validates and returns:

const generateDocTool = tool({
  description: "Generate structured documentation",
  inputSchema: MyDocSchema,           // Zod schema IS the output shape
  execute: async (data) => data,       // Validate and return
});

LLM-resilient enums — LLMs sometimes append extra text to enum values. Use lenient transforms:

const LenientCategory = z.string().transform((val) => {
  const valid = ["Business", "Technical", "Legal"] as const;
  return valid.find((c) => val.startsWith(c)) ?? "Business";
});

Building a new chatbot

When scaffolding from scratch, read checklist.md for the full setup sequence.

Theming

Theme setup belongs to /nextjs-shadcn: oklch variables in globals.css,

Content truncated.