nextjs-chatbot skill for Claude Code: Next.js chat UI setup
nextjs-chatbot guides a production web chat in Next.js: tool approval, saved conversations, rendered tool results, follow-up suggestions and an embeddable widget.
MIT 161 installs ★ 74 updated 2026-10-18
npx skills add laguagu/claude-code-nextjs-skills --skill nextjs-chatbot -a claude-codeWhat nextjs-chatbot does
The skill covers the web-chat side of a Next.js app: approving tool calls, storing conversations, showing what a tool returned, retrieval with sources, suggested next steps and a widget you can drop into another page. Each topic lives in its own file: hitl.md, persistence.md, tool-rendering.md, popup-widget.md, search.md, suggestions.md, web-search.md, testing.md. The skill opens the one that matches the feature at hand.
It works with whatever stack the project already runs. When nothing is decided yet, it names Bun, the AI Elements patterns from shadcn/ui, Drizzle plus PostgreSQL for server-side history, and a fast model with little or no reasoning. Line up ai, @ai-sdk/react and provider versions before writing API calls, or the types and callbacks won't match: ai-sdk-7 for v7, ai-sdk-6 for v6.
Conversation access gets authenticated and tools get authorized on the server, since browser history, model IDs and consent flags can't be trusted. It also asks you to check how your proxy streams and buffers; hand-built NDJSON or SSE progress needs the right headers to reach the browser.
What it helps with
- gate a tool call behind user approval
- restore a conversation after a page reload
- render tool output as readable UI instead of raw JSON
- embed the chat as a widget on a host page
- verify that the proxy streams instead of buffering
Example prompts for the agent
- Add approval before the tool runs and show its result as a separate block.
- Persist the chat in PostgreSQL and bring it back after a reload.
- Build an embeddable chat widget for a host page.
How to install nextjs-chatbot
1Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill nextjs-chatbot -a claude-code2Manually: put the files in place
~/.claude/skills/nextjs-chatbot/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/nextjs-chatbot/
1Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill nextjs-chatbot -a codex2Manually: put the files in place
.agents/skills/nextjs-chatbot/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill nextjs-chatbot -a cursor2Manually: put the files in place
.cursor/skills/nextjs-chatbot/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install laguagu/claude-code-nextjs-skills skills/nextjs-chatbot2Manually: put the files in place
.github/skills/nextjs-chatbot/SKILL.md1Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill nextjs-chatbot -a gemini-cli2Platform CLI
gemini skills install https://github.com/laguagu/claude-code-nextjs-skills --path skills/nextjs-chatbotManually: put the files in place
.devin/skills/nextjs-chatbot/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill nextjs-chatbot -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about nextjs-chatbot
How do I install nextjs-chatbot in Claude Code?
Run npx skills add laguagu/claude-code-nextjs-skills --skill nextjs-chatbot -a claude-code. The skill lands at ~/.claude/skills/nextjs-chatbot/SKILL.md.
What does nextjs-chatbot do?
It walks through web-chat integration in Next.js: tool approval, stored conversations, rendered tool results, retrieval, suggestions and an embeddable widget.
Which versions should I match before writing API calls?
ai, @ai-sdk/react and the provider package. The skill points to ai-sdk-7 for v7 projects and ai-sdk-6 for v6.
Source text
SKILL.md · MIT
--- 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.
© laguagu · MIT · laguagu/claude-code-nextjs-skills