nextjs-chatbot

What this skill does

# Next.js Chatbot

Opinionated blueprint for production **web** chatbots. Focuses on patterns **not** covered by `/ai-sdk-6`, `/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:** `gpt-5.4` with `reasoningEffort: "none"`
- **AI SDK:** `ai@6` — `ToolLoopAgent`, `createAgentUIStreamResponse`
- **UI:** shadcn/ui + ai-elements (see `/ai-elements` for component docs)
- **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](https://nextjs.org/docs/app/guides/mcp)
- **ai-elements** (via `mcp-remote` → `https://registry.ai-sdk.dev/api/mcp`) — component registry search

Add both to `.claude/settings.json` mcpServers.

## Agent setup

```ts
export function createAgent(opts?: { model?: LanguageModel }) {
  return new ToolLoopAgent({
    model: opts?.model ?? openai("gpt-5.4"),
    instructions,
    providerOptions: { openai: { reasoningEffort: "none" } },
    tools,
    stopWhen: stepCountIs(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.

## Route handler

```ts
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" }),
    onFinish: async ({ messages }) => { /* save to DB — see persistence.md */ },
  });
}
```

### Azure OpenAI model routing

Non-reasoning models (gpt-4o) must use Chat Completions API (`azure.chat()`) — Responses API causes `fc_` ID errors on multi-turn tool calls. Reasoning models (gpt-5.x, o-series) use Responses API (default):

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

Set `reasoningEffort` only for reasoning models to avoid warnings.

## Client transport patterns

### Dynamic context via transport body

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

```ts
// 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:

```ts
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:

```ts
// 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:

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

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

## 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:

```ts
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:

```ts
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](checklist.md) for the full setup sequence.

## Theming

Always use `globals.css` oklch color variables — never hardcode colors. Define brand identity in `:root`:

```css
/* Example: warm gold brand */
:root {
  --primary: oklch(0.84 0.05 85);           /* brand color */
  --primary-foreground: oklch(0.15 0.02 85);
  --muted: oklch(0.95 0.01 85);
  --muted-foreground: oklch(0.45 0.02 85);
  --font-sans: var(--font-sans), system-ui, sans-serif;
}
```

Use `/nextjs-shadcn` for full theme setup. Key rules:
- All components reference CSS variables, not literal colors
- Match the brand identity across chat bubble, buttons, borders, scrollbar
- User messages: `bg-muted` rounded bubble (right-aligned)
- Assistant messages: full-width, no background

## Message streaming state & feedback visibility

Gate action icons (copy, thumbs up/down, regenerate) and inter-tool shimmers on the **chat-level stream status**, not tool-part states alone. During a multi-tool response (tool A finishes → tool B starts), all tool parts are briefly in a non-loading state and `!toolParts.some(isToolLoading)` flips true → icons and shimmers flicker on/off.

Correct pattern:

```tsx
// Parent widget — derive from useChat's status
const { messages, status } = useChat({ transport, experimental_throttle: 50 });
const isGenerating = status === "streaming" || status === "submitted";

{messages.map((m, i) => (
  <ChatMessage
    key={m.id}
    message={m}
    isGenerating={isGenerating}
    isLast={i === messages.length - 1}
  />
))}

// ChatMessage
const isStreaming = isGenerating && isLast && message.role === "assistant";
const showActions = !isStreaming && hasContent;

{showActions && <MessageActions>…</MessageActions>}
```

`isGenerating` stays `true` for the entire tool-loop + text-generation span, so `isStreaming` never flips between tools. Pair with `experimental_throttle: 50` on `useChat` to smooth rapid UI updates — this is the client-side knob, distinct from the server-side `smoothStream` text transform.

## Message actions

Every assistant message renders an action toolbar below text: Copy, ThumbsUp, ThumbsDown, Regenerate, Delete —