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

> Start Lobe Chat development easily Clone the repo install dependencies and run pnpm dev to launch the Nextjs backend and Vite frontend simultaneously

- Repository: [LobeHub/lobe-chat](https://github.com/lobehub/lobe-chat)
- Tags: getting-started
- Published: 2026-03-03

---

**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"`).

```bash
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`](https://github.com/lobehub/lobe-chat/blob/canary/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`](https://github.com/lobehub/lobe-chat/blob/main/src/app/layout.tsx) |
| **State** | Zustand 5 | Global lightweight state | [`src/store/video/store.ts`](https://github.com/lobehub/lobe-chat/blob/main/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:

```bash
cp .env.example .env

```

Required variables include:

```bash

# 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:

```bash
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:

```bash

# 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:

```bash

# Unit and integration tests (Vitest)

pnpm test

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

pnpm e2e

```

Configuration files: `vitest.config.mts` and [`e2e/tsconfig.json`](https://github.com/lobehub/lobe-chat/blob/main/e2e/tsconfig.json).

## Building for Production

Create a production build using:

```bash
pnpm build

```

For containerized deployment:

```bash
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`](https://github.com/lobehub/lobe-chat/blob/main/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.