deer-flow/frontend/AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Codex, and others) when working with the DeerFlow frontend. It is the source of truth; the sibling CLAUDE.md imports it via @AGENTS.md.

Project Overview

DeerFlow Frontend is a Next.js 16 web interface for an AI agent system. It communicates with a LangGraph-based backend to provide thread-based AI conversations with streaming responses, artifacts, and a skills/tools system.

Stack: Next.js 16, React 19, TypeScript 5.8, Tailwind CSS 4, pnpm 10.26.2. Requires Node.js 22+ and pnpm 10.26.2+.

Core dependencies

• LangGraph SDK (@langchain/langgraph-sdk ^1.5.3) — Agent orchestration and streaming
• LangChain Core (@langchain/core ^1.1.15) — Fundamental AI building blocks
• TanStack Query (@tanstack/react-query ^5.90.17) — Server state management
• UI: Shadcn UI, MagicUI, React Bits, and Vercel AI SDK elements (generated from registries — see Code Style)

Commands

Command	Purpose
pnpm dev	Dev server with Turbopack (http://localhost:3000)
pnpm build	Production build
pnpm check	Lint + type check (run before committing)
pnpm lint	ESLint only
pnpm lint:fix	ESLint with auto-fix
pnpm format	Prettier check (pnpm format:write to apply)
pnpm test	Run unit tests with Rstest
pnpm test:e2e	Run E2E tests with Playwright (Chromium)
pnpm typecheck	TypeScript type check (tsc --noEmit)
pnpm start	Start production server

Unit tests live under tests/unit/ and mirror the src/ layout (e.g., tests/unit/core/api/stream-mode.test.ts tests src/core/api/stream-mode.ts). Powered by Rstest; import source modules via the @/ path alias.

Rstest runs them as two projects (rstest.config.ts). *.test.ts / *.test.tsx run in a plain node environment — that is nearly the whole suite, and it is the default for anything that is pure logic. *.dom.test.ts / *.dom.test.tsx run in happy-dom, for tests that need a document: hooks driven through renderHook from @testing-library/react, and components. Keep the split — a DOM environment costs roughly 3x the runtime of the node suite, so tests that do not render should not opt into it. A hook whose behavior only exists under real React (effect ordering, cleanup on unmount, re-render on store change) belongs in a .dom.test.* file rather than a node test that mocks react itself.

E2E tests live under tests/e2e/ and use Playwright with Chromium. They mock all backend APIs via page.route() network interception and test real page interactions (navigation, chat input, streaming responses). Config: playwright.config.ts.

Architecture

Frontend (Next.js) ──▶ LangGraph SDK ──▶ LangGraph Backend (lead_agent)
                                              ├── Sub-Agents
                                              └── Tools & Skills

The frontend is a stateful chat application. Users create threads (conversations), send messages, set thread-scoped /goal completion conditions, and receive streamed AI responses. The backend orchestrates agents that can produce artifacts (files/code), todos, and goal state updates.

Source Layout (src/)

• app/ — Next.js App Router. Routes include / (landing), /showcase/[thread_id] (allowlisted public read-only demos), /workspace/chats/[thread_id] (authenticated chat), /workspace/agents/[agent_name] and /workspace/agents/new (custom agents), /blog/…, the (auth)/{login,setup,auth/callback} flow, /[lang]/docs/…, and /api/… route handlers (e.g. /api/memory).
• components/ — React components:
  • ui/ — Shadcn UI primitives (auto-generated, ESLint-ignored)
  • ai-elements/ — Vercel AI SDK elements (auto-generated, ESLint-ignored)
  • workspace/ — Chat page components (messages, artifacts, settings)
  • landing/ — Landing page sections
  • docs/ — Docs / MDX rendering components
• core/ — Business logic, the heart of the app. Domains include threads/ (creation, streaming, state), api/ (LangGraph client singleton), agents/ (custom agents), auth/ (authentication), artifacts/, channels/ (IM connections), integrations/ (managed third-party integration status/install clients such as Lark CLI), i18n/ (en-US, zh-CN), settings/, memory/, skills/, messages/, mcp/, models/, input-polish/ (pre-send draft rewrite API), voice-input/ (browser speech-recognition helpers), suggestions/, tasks/, todos/, tools/, workspace-changes/ (run-scoped changed-file summaries and diff fetching), config/, notification/, blog/, plus rendering helpers (rehype/, streamdown/) and utils/.
• hooks/ — Shared React hooks
• lib/ — Utilities (cn() from clsx + tailwind-merge)
• content/ — MDX content (blog posts, docs) rendered by the app
• styles/ — Global CSS with Tailwind v4 @import syntax and CSS variables for theming
• typings/ — Ambient TypeScript declarations
• Root files: env.js (env validation), mdx-components.ts (MDX component map)

More specific AGENTS.md files under src/ contain the frontend sections split from this file.

Code Style

• Imports: Enforced ordering (builtin → external → internal → parent → sibling), alphabetized, newlines between groups. Use inline type imports: import { type Foo }.
• Unused variables: Prefix with _.
• Class names: Use cn() from @/lib/utils for conditional Tailwind classes.
• Path alias: @/* maps to src/*.
• Components: ui/ and ai-elements/ are generated from registries (Shadcn, MagicUI, React Bits, Vercel AI SDK) — don't manually edit these.

Environment

Backend API URLs are optional; an nginx proxy is used by default:

NEXT_PUBLIC_BACKEND_BASE_URL=http://localhost:8001
NEXT_PUBLIC_LANGGRAPH_BASE_URL=http://localhost:8001/api

Leave these unset for the standard make dev / Docker flow, where nginx serves the public /api/langgraph/* prefix and rewrites it to Gateway's native /api/* routes.

To reach a dev server on anything other than localhost — a LAN address, or a proxied hostname — list the host in DEER_FLOW_DEV_ALLOWED_ORIGINS (comma-separated; a full URL is reduced to its host). It feeds Next's allowedDevOrigins, which gates /_next/*, fonts, and HMR. Without it those requests get a 403 and the page renders server-side but never hydrates, so nothing on it — including the login form — responds. Development only; production builds ignore it.

Resources

• LangGraph Documentation
• LangChain Core Concepts
• TanStack Query Documentation
• Next.js App Router

Contributing

When adding features:

1. Follow the established src/ structure
2. Add TypeScript types and proper error handling
3. Write unit tests under tests/unit/ (pnpm test) and E2E tests under tests/e2e/ (pnpm test:e2e)
4. Run pnpm check before committing
5. Update this AGENTS.md when architecture, commands, or conventions change

Route asset budgets are enforced with pnpm perf:check. The command measures /login from a normal production build, then builds in static-demo mode for the fixture-backed workspace routes. It starts the production server on temporary local ports, measures the unique JavaScript and CSS files referenced by representative routes, writes the detailed result to .next/performance-results.json, and compares totals with performance-budgets.json. Fix route ownership or split points when a budget fails; do not raise a ceiling without documenting and reviewing the measured regression.