tools-only Frontend Interface (Next.js + Weaviate Backend)
Quick reference
| Item | Value |
|---|---|
| Stack | Next.js (App Router), Tailwind v4, shadcn/ui, Framer Motion, react-icons, ai-sdk |
| Node | v25.3.0+ |
| Backend | NEXT_PUBLIC_BACKEND_HOST (default: localhost:8000) |
| App type | Single-page app; main view updates in place, no full-page navigations |
| Layout | shadcn Sidebar (left) + main content area; sidebar buttons switch the main view per feature |
Setup (run in order)
1. Next.js
- Command:
npx create-next-app@latest . --yes(run from repo root; may needrequired_permissions: ["all"]in sandbox) - Result: TypeScript, ESLint, Tailwind v4, App Router, Turbopack,
@/*→./*, nosrc/. App inapp/, static inpublic/. - Scripts:
dev|build|start|lint. Dev server: http://localhost:3000. - Routes:
app/layout.tsx,app/page.tsx. Imports:@/= project root. - Ref: Next.js App Router Installation — verify against current docs.
2. shadcn/ui
- Requires: Next.js + Tailwind v4 + App Router +
@/*, nosrc/. - Init:
npx shadcn@latest init -t next -y -b zinc --no-src-dir - Add components:
npx shadcn@latest add button -y(e.g.card,dialog,input;-ooverwrites). - Output:
components.json,lib/utils.ts(cn),app/globals.css(tw-animate, shadcn/tailwind.css, CSS vars). UI incomponents/ui/<name>.tsx. Import:import { Button } from "@/components/ui/button". - Ref: shadcn Next.js | CLI.
3. Framer Motion
npm i framer-motion
- Ref: Framer Motion
4. AI SDK (optional)
Note: Install only when create a conversational user interface for your chatbot application. It enables the streaming of chat messagesyou need to stream responses from the backend using useChat().
- When: Add this step only if the app needs a chat UI (e.g. query-agent or chatbot flows).
- Stack: Use the Vercel AI SDK (
ai+@ai-sdk/*). UseuseChatand SDK UI primitives for the chat view. - Ref: AI SDK – useChat | Next.js App Router setup — follow current docs for install and wiring.
npm i ai @ai-sdk/react zod
5. Environment
Required:
NEXT_PUBLIC_BACKEND_HOST="localhost:8000"
Use the actual backend host when not local.
Rules (must follow)
Stack and structure
- UI: Use shadcn components only for layout and interactive elements (buttons, cards, inputs, dialogs, etc.). Do not add another UI library.
- Architecture: SPA — one main page, update main view in place. Avoid full-page navigations unless necessary.
- Icons: Use react-icons only; prefer one set (e.g.
react-icons/faorreact-icons/hi) for consistency. - Animation: Use Framer Motion only. Do not add another animation library.
Visual style
- Goal: Minimal, sleek, clean. No clutter, heavy borders, or noisy backgrounds.
- Aesthetic: “Liquid glass” — frosted, translucent; soft blur; light borders and shadows; depth without heaviness. Use
backdrop-blur, semi-transparent fills, subtle gradients where they support this.
Motion
- Style: Subtle, springy, purposeful (fade in, hover, enter/exit). Prefer spring physics over linear/ease-out.
Layout
- Left: shadcn Sidebar component.
- Right: Main content area.
- Navigation: One sidebar button per backend feature (e.g. data explorer, chat). Click switches the main view only.
Responsiveness
- Layout and components must work on small and large screens.