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

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.

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.

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:

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:

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:

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:

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:

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, 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.

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/.

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