# How to Build Lobe Chat from Source: A Complete Developer Guide

> Build Lobe Chat from source by cloning the repository, installing dependencies, configuring variables, and running pnpm dev for local development. Get the complete developer guide.

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

---

**To build Lobe Chat from source, clone the lobehub/lobe-chat repository, install dependencies with pnpm, configure your environment variables, and run `pnpm dev` to start the full-stack development server on localhost:3000.**

Lobe Chat (also referred to as LobeHub) is a modern, full-stack AI-agent workspace built with **Next.js 16** and a **Vite-based SPA** frontend. Whether you want to customize the UI, add new features, or deploy a self-hosted instance, building from source gives you complete control over the application. This guide walks you through cloning the repository, installing dependencies, and running both development and production builds.

## Prerequisites for Building Lobe Chat

Building Lobe Chat requires **Node.js 18 or higher** and the **pnpm** package manager to handle the monorepo workspace. While optional, installing **bun** enables faster script execution for SPA-only development, and **Docker** provides a containerized deployment path.

Before running the application, copy the `.env.example` file to `.env` and populate the required environment variables such as `OPENAI_API_KEY` and database connection strings.

## Clone and Install Dependencies

Start by cloning the official repository and navigating into the project directory. The default branch is `canary`, which contains the latest stable development code.

```bash
git clone https://github.com/lobehub/lobe-chat.git
cd lobe-chat

```

Install all workspace dependencies using pnpm. This command resolves packages across the monorepo structure defined in [`pnpm-workspace.yaml`](https://github.com/lobehub/lobe-chat/blob/main/pnpm-workspace.yaml).

```bash
pnpm install

```

## Development Workflows

Lobe Chat supports two distinct development modes depending on whether you need the full backend API or just the frontend UI.

### Full-Stack Development Mode

Run the complete application stack with the following command:

```bash
pnpm dev

```

This starts the **Next.js server** on `http://localhost:3000` and the **Vite SPA** on a dynamic port. API calls route through the Next.js backend located in `src/app/`, while the React 19 frontend in `src/spa/` receives hot-module replacement (HMR) updates instantly.

### SPA-Only Development Mode

For pure UI development without a local backend, use:

```bash
bun run dev:spa

```

This launches only the Vite frontend on `http://localhost:9876`. The configuration proxies API requests to the production backend at `https://app.lobehub.com`, allowing you to test against live data without running the server components locally.

## Building for Production

Generate optimized production bundles for deployment with the standard build command:

```bash
pnpm build

```

This executes `next build` for the server-side application in `src/app/` and `vite build` for the SPA in `src/spa/`, outputting to `.next/` and `dist/` directories respectively. To start the production server locally:

```bash
pnpm start

```

## Docker Deployment from Source

For containerized self-hosting, the repository provides a complete Docker setup. Initialize a persistent data directory and run the automated setup script:

```bash
mkdir lobe-chat-db && cd lobe-chat-db
bash <(curl -fsSL https://lobe.li/setup.sh)
docker compose up -d

```

The setup script configures the database schema and generates the required `.env` file. The `Dockerfile` in the repository root and the compose configuration in `docker-compose/` handle the multi-stage build process, exposing the application on the configured port.

## Project Architecture Overview

Understanding the source structure helps navigate the codebase effectively. The repository organizes code into three logical layers:

- **`src/app/`** – Next.js 16 app router containing API routes, authentication handlers, and server-only utilities.
- **`src/spa/`** – Vite-based SPA entry points ([`entry.client.tsx`](https://github.com/lobehub/lobe-chat/blob/main/entry.client.tsx), [`entry.server.tsx`](https://github.com/lobehub/lobe-chat/blob/main/entry.server.tsx)) and React 19 UI components.
- **`src/store/`** – Zustand state management stores for chat history, user settings, and feature flags.
- **`packages/`** – Shared monorepo packages including the web crawler, UI component library, and database adapters defined in [`drizzle.config.ts`](https://github.com/lobehub/lobe-chat/blob/main/drizzle.config.ts).

## Summary

- Clone the `lobehub/lobe-chat` repository and run `pnpm install` to prepare the monorepo workspace.
- Copy `.env.example` to `.env` and configure required API keys and database connections before starting the server.
- Use `pnpm dev` for full-stack development (Next.js + Vite) or `bun run dev:spa` for frontend-only development on port 9876.
- Build production bundles with `pnpm build` and deploy via Docker using the provided setup script and compose configuration.

## Frequently Asked Questions

### What is the minimum Node.js version required to build Lobe Chat?

You need **Node.js 18 or higher** to build Lobe Chat from source. The build system relies on modern Node features for the Next.js 16 server and Vite-based SPA compilation.

### Can I run the frontend without building the backend?

Yes. Run `bun run dev:spa` to start only the Vite SPA on `http://localhost:9876`. This mode proxies API calls to the production backend at `https://app.lobehub.com`, allowing you to develop the UI without local server infrastructure.

### How do I deploy Lobe Chat using Docker?

Create a data directory, run the automated setup script `bash <(curl -fsSL https://lobe.li/setup.sh)` to initialize the database and environment variables, then execute `docker compose up -d`. The Dockerfile and compose configuration in the repository handle the multi-stage build automatically.

### Where are the main source directories located?

The server-side code resides in `src/app/` (Next.js routes and API handlers), the client-side SPA lives in `src/spa/` (Vite entry points and React components), and shared state management is located in `src/store/` (Zustand stores). Monorepo packages are organized under `packages/`.