laguagu/claude-code-nextjs-skills / skills/nextjs-chatbot
nextjs-chatbot
VerifiedProduction Next.js web-chat integration: tool approval, persisted conversations, tool result UI, grounded retrieval, follow-up suggestions and embedded widgets. Use when building or debugging a web chatbot that needs these features. Use nextjs-shadcn for scaffolding and ai-sdk for general SDK APIs; multi-platform bots use Chat SDK.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.6 KB |
| hitl.md | markdown | 4.1 KB |
| persistence.md | markdown | 4.0 KB |
| popup-widget.md | markdown | 1.6 KB |
| search.md | markdown | 1.8 KB |
| suggestions.md | markdown | 1.4 KB |
| testing.md | markdown | 2.2 KB |
| tool-rendering.md | markdown | 1.7 KB |
| web-search.md | markdown | 1.6 KB |
SKILL.md
View on GitHub---
name: nextjs-chatbot
description: "Production Next.js web-chat integration: tool approval, persisted conversations, tool result UI, grounded retrieval, follow-up suggestions and embedded widgets. Use when building or debugging a web chatbot that needs these features. Use nextjs-shadcn for scaffolding and ai-sdk for general SDK APIs; multi-platform bots use Chat SDK."
---
# Production Next.js chatbots
Use this skill for web-chat integration: persisted conversations, tool approval,
tool result UI and an embedded widget. Use `nextjs-shadcn` for scaffolding,
`ai-sdk` to resolve the SDK version, and the `shadcn` skill for chat components.
An existing elements.ai-sdk.dev install keeps its copied source in
`components/ai-elements/` as the reference until it migrates (deprecated upstream
at the end of November 2026; see https://ui.shadcn.com/docs/ai-elements).
For multi-platform messaging, consult [Chat SDK](https://chat-sdk.dev/).
Keep the project's stack. Choose the model, reasoning setting, storage and
client state from the product's quality, latency and privacy requirements.
A chatbot does not inherently need PostgreSQL, Zustand, MCP servers or every
message action. When a new project has not decided, the defaults are Bun,
the AI Elements patterns from shadcn/ui (Message, Bubble, Message Scroller,
Trace; https://ui.shadcn.com/docs/ai-elements), Drizzle + PostgreSQL for
server-side history, and a
fast model with low or no reasoning effort, because chat latency is the product.
Read the installed `node_modules/ai/docs/04-ai-sdk-ui/` for persistence, tool
usage, errors and resume streams; use the package's types and `src/` when
shipped for exact contracts.
The linked ai-sdk.dev pages are the online fallback and describe the newest major.
## Integration contracts
- Match `ai`, `@ai-sdk/react` and provider versions before writing API calls.
Use `ai-sdk-7` for v7 and `ai-sdk-6` for existing v6 projects; core callback
renames do not imply renaming the separate `useChat.onFinish`.
- Authenticate conversation access, validate request data and authorize tools
on the server. Client history, context, model IDs and consent flags are
untrusted; prompts cannot enforce tenant isolation or permissions.
- Store validated UI messages with stable IDs when the full conversation UI
must be restored. Convert model history through the installed SDK's helpers;
keep required tool-call/result and provider reasoning relationships intact.
- Determine what happens on cancellation, disconnect, reload and retries.
Consuming a stream after disconnect still depends on the hosting lifetime;
durable execution needs a supported durable runtime.
- Log redacted diagnostics with a correlation ID. Return a safe public error
for failed HTTP requests and in-stream failures; an error after headers have
been sent cannot change the HTTP status. The UI stream masks ordinary errors
by default; provider-executed tool errors can bypass `onError`, so check the
tool error renderer too. A custom `onError` return value reaches the browser
verbatim, and a non-2xx response reaches `useChat` `onError` with the raw
response body as its message.
- Verify actual proxy streaming and buffering configuration. SDK UI-message
responses already send `X-Accel-Buffering: no`; streams you build yourself
(NDJSON/SSE progress) need it and `Cache-Control: no-store, no-transform`.
The header helps supported nginx setups; it does not guarantee that every
host streams without buffering.
## Chat surface
Keep the answer, relevant tool results and useful sources readable. Default
layout: user messages in a right-aligned `bg-muted` bubble, assistant messages
full width without a background, and the brand carried through to the
scrollbar. Add feedback, regenerate, delete or suggestions when the product
needs them; avoid a repeated “Answer” heading or an action toolbar on every
message by default. Use the `icons` skill for icon choice and `nextjs-shadcn`
for the surrounding interface.
Follow streamed output while the reader is at the bottom; preserve their place
when they scroll away or load earlier history. Use an existing compatible
scroll primitive when it fits; shadcn's
[Message Scroller](https://ui.shadcn.com/docs/react/message-scroller) is one option;
anchor on the user's message so the reply streams below it.
Render Markdown through the application's
renderer (Streamdown through the shadcn/ui Message pattern's `Markdown`
component in the default stack; `MessageResponse` in existing AI Elements
installs)
and style it with shadcn Typeset by default (CSS only, see `nextjs-shadcn`);
verify nested lists, long links and code blocks.
Derive turn completion from `useChat` status (`submitted`/`streaming`) rather
than a momentary gap between tools. Stop or isolate the generation before
switching conversations. Browser storage must not make the first client render disagree
with server-rendered consent or history.
## Read for the feature
- [Tool approval](hitl.md): policy, replay security and UI transitions.
- [Persistence](persistence.md): IDs, history replay, feedback and resumption.
- [Tool rendering](tool-rendering.md): typed states and safe output.
- [Popup/embedding](popup-widget.md): focus, scrolling and host boundaries.
- [Retrieval](search.md): structured filters and evaluated search choices.
- [Suggestions](suggestions.md): optional, grounded next actions.
- [Web search](web-search.md): source scope, freshness and provider capability.
- [Verification](testing.md): UI transitions and model/retrieval evals.
Exercise a second turn after restoring history, approval and denial, tool
failure, cancellation, fast conversation switching and the deployed stream
path. Report the behaviors actually checked.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |