deer-flow/frontend/README.md

DeerFlow Frontend

Like the original DeerFlow 1.0, we would love to give the community a minimalistic and easy-to-use web interface with a more modern and flexible architecture.

Tech Stack

• Framework: Next.js 16 with App Router
• UI: React 19, Tailwind CSS 4, Shadcn UI, MagicUI and React Bits
• AI Integration: LangGraph SDK and Vercel AI Elements

Quick Start

Prerequisites

• Node.js 22+
• pnpm 10.26.2+

Installation

# Install dependencies
pnpm install

# Copy environment variables
cp .env.example .env
# Edit .env with your configuration

Development

# Start development server
pnpm dev

# The app will be available at http://localhost:3000

Build & Test

# Type check
pnpm typecheck

# Check formatting
pnpm format

# Apply formatting
pnpm format:write

# Lint
pnpm lint

# Run unit tests
pnpm test

# One-time setup: install Playwright Chromium browser
pnpm exec playwright install chromium

# Run E2E tests (builds and starts production server automatically)
pnpm test:e2e

# Build for production
pnpm build

# Start production server
pnpm start

Site Map

├── /                    # Landing page
├── /chats               # Chat list
├── /chats/new           # New chat page
└── /chats/[thread_id]   # A specific chat page

Configuration

Environment Variables

Key environment variables (see .env.example for full list):

# Backend API URL (optional, uses local Next.js/nginx proxy by default)
NEXT_PUBLIC_BACKEND_BASE_URL="http://localhost:8001"
# LangGraph-compatible API URL (optional, uses local Next.js/nginx proxy by default)
NEXT_PUBLIC_LANGGRAPH_BASE_URL="http://localhost:8001/api"

Project Structure

tests/
├── e2e/                    # E2E tests (Playwright, Chromium, mocked backend)
└── unit/                   # Unit tests (mirrors src/ layout)
src/
├── app/                    # Next.js App Router pages
│   ├── api/                # API routes
│   ├── showcase/           # Allowlisted public read-only demos
│   ├── workspace/          # Main workspace pages
│   └── mock/               # Mock/demo pages
├── components/             # React components
│   ├── ui/                 # Reusable UI components
│   ├── workspace/          # Workspace-specific components
│   ├── landing/            # Landing page components
│   └── ai-elements/        # AI-related UI elements
├── core/                   # Core business logic
│   ├── api/                # API client & data fetching
│   ├── artifacts/          # Artifact management
│   ├── config/              # App configuration
│   ├── i18n/               # Internationalization
│   ├── mcp/                # MCP integration
│   ├── messages/           # Message handling
│   ├── models/             # Data models & types
│   ├── settings/           # User settings
│   ├── skills/             # Skills system
│   ├── threads/            # Thread management
│   ├── todos/              # Todo system
│   └── utils/              # Utility functions
├── hooks/                  # Custom React hooks
├── lib/                    # Shared libraries & utilities
├── server/                 # Server-side code
│   └── better-auth/        # Authentication setup and session helpers
└── styles/                 # Global styles

Scripts

Command	Description
pnpm dev	Start development server (Webpack on Windows, Turbopack elsewhere)
pnpm build	Build for production
pnpm start	Start production server
pnpm test	Run unit tests with Rstest
pnpm test:e2e	Run E2E tests with Playwright
pnpm format	Check formatting with Prettier
pnpm format:write	Apply formatting with Prettier
pnpm lint	Run ESLint
pnpm lint:fix	Fix ESLint issues
pnpm typecheck	Run TypeScript type checking
pnpm check	Run both lint and typecheck

Development Notes

• Uses pnpm workspaces (see packageManager in package.json)
• Turbopack is used by default in development except on Windows, where Webpack avoids known Turbopack runtime instability. Set DEER_FLOW_DEV_BUNDLER=turbo or DEER_FLOW_DEV_BUNDLER=webpack to override the platform default for local diagnosis.
• Environment validation can be skipped with SKIP_ENV_VALIDATION=1 (useful for Docker)
• Backend API URLs are optional; nginx proxy is used by default in development

License

MIT License. See LICENSE for details.