How to Get Started with Lobe Chat Development: A Complete Guide

Clone the repository, install dependencies with pnpm, configure environment variables, and run pnpm dev to start the Next.js backend and Vite frontend simultaneously.

Lobe Chat (lobehub/lobe-chat) is a full-stack AI-agent workspace built on a modern Next.js 16 + React 19 stack. This guide covers everything you need to know about Lobe Chat development, from initial setup to running tests and contributing code.

Clone and Install Dependencies

Start by cloning the monorepo and installing dependencies. The project requires pnpm 10 (specified in package.json → "packageManager").

git clone https://github.com/lobehub/lobe-chat.git
cd lobe-chat
pnpm install

This installs the entire monorepo, including the desktop app (apps/desktop/), shared packages (packages/), and the main Next.js application.

Project Structure Overview

Understanding the directory layout is essential for effective Lobe Chat development:

lobe-chat/
├── apps/desktop/                     # Electron desktop client

├── packages/                         # Shared packages @lobechat/*

│   ├── database/                     # Drizzle ORM schema & repos

│   ├── agent-runtime/                # Agent execution engine

│   └── …
├── src/                              # Main Next.js application

│   ├── app/                          # Next.js App Router (pages, API, auth)

│   ├── features/                     # Domain-level UI & logic

│   ├── store/                        # Zustand stores (e.g., video/store.ts)

│   ├── services/                     # Client-side tRPC hooks

│   └── utils/                        # Helper utilities

├── locales/                          # i18n translation files

└── e2e/                              # Playwright + Cucumber tests

The architecture is documented in docs/development/start.mdx.

Core Technology Stack

Lobe Chat development relies on a carefully selected stack for type safety and performance:

Layer	Technology	Role	Key Files
Framework	Next.js 16 + React 19	SSR, routing, API routes	src/app/layout.tsx
State	Zustand 5	Global lightweight state	src/store/video/store.ts
API	tRPC	End-to-end type-safe RPC	src/libs/trpc/*
Database	Drizzle ORM + PostgreSQL	Type-safe queries	packages/database/*
UI	Ant Design + @lobehub/ui	Component library	src/components/*
Testing	Vitest + Playwright	Unit and E2E tests	vitest.config.mts, e2e/*

Configure Environment Variables

Before running the dev server, copy the example environment file and configure your API keys:

cp .env.example .env

Required variables include:

# AI Provider Keys

OPENAI_API_KEY=sk-xxxxxxxxxxxxx
OPENAI_PROXY_URL=https://api.openai.com/v1

# Database (PostgreSQL)

POSTGRES_URL=postgresql://postgres:password@localhost:5432/lobe

The project uses @t3-oss/env-nextjs for type-safe environment validation (see src/envs/*).

Start the Development Server

Lobe Chat development uses a single command to orchestrate both the backend and frontend:

pnpm dev

This runs scripts/devStartupSequence.mts, which:

1. Spawns npm run dev:next → Next.js on localhost:3010
2. Spawns npm run dev:spa → Vite SPA on localhost:9876
3. Performs pre-warm health checks (lines 57-84 in devStartupSequence.mts)

You can also run services separately:

# Terminal 1 - Backend + Auth

npm run dev:next

# Terminal 2 - Frontend SPA

npm run dev:spa

Running Tests

Validate your changes with the comprehensive test suite:

# Unit and integration tests (Vitest)

pnpm test

# End-to-end tests (Playwright + Cucumber)

pnpm e2e

Configuration files: vitest.config.mts and e2e/tsconfig.json.

Building for Production

Create a production build using:

pnpm build

For containerized deployment:

docker compose up -d

The repository includes optimized Docker configurations at the root level.

Summary

• Lobe Chat development requires pnpm 10 for dependency management in this Next.js 16 monorepo.
• Run pnpm dev to start both the Next.js backend (localhost:3010) and Vite frontend (localhost:9876) via the devStartupSequence.mts orchestrator.
• Configure environment variables in .env using .env.example as a template, including OPENAI_API_KEY and POSTGRES_URL.
• The architecture separates concerns across src/app/ (routing), src/store/ (Zustand state), packages/database/ (Drizzle ORM), and src/libs/trpc/ (type-safe APIs).
• Execute pnpm test for Vitest unit tests and pnpm e2e for Playwright end-to-end tests.

Frequently Asked Questions

What package manager does Lobe Chat use?

Lobe Chat uses pnpm 10 as its package manager, specified in the packageManager field of package.json. You must use pnpm to install dependencies in this monorepo workspace; npm or yarn are not supported.

Which ports are used during local development?

The development stack uses two main ports: 3010 for the Next.js backend (API routes and authentication) and 9876 for the Vite-powered SPA frontend. These are configured in scripts/devStartupSequence.mts and can be customized via CLI flags.

How do I run only the backend or frontend?

You can run services independently using npm run dev:next for the Next.js backend alone or npm run dev:spa for the Vite frontend alone. This is useful when debugging specific layers of the application without the orchestration overhead of pnpm dev.

Where are the database schemas defined?

Database schemas are defined in packages/database/ using Drizzle ORM. This package contains the PostgreSQL schema definitions, repository patterns, and migration scripts that power the application's persistence layer, separate from the Next.js application code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}