Developer Setup
Relevant source files
The following files were used as context for generating this wiki page:
This document provides a comprehensive guide for developers to set up their local environment, understand the project structure, and follow the established workflows for contributing to the LobeChat project. The project is a modern AI chat application built with Next.js and organized as a monorepo.
The development process emphasizes type safety, extensive testing, and a structured Git workflow to maintain code quality and consistency. Adherence to these guidelines is crucial for all team members.
Sources: AGENTS.md:3-5, AGENTS.md:13-14, CLAUDE.md:3-4
Tech Stack
LobeChat is built using a modern technology stack. The key technologies are listed below.
| Category | Technology | Description |
|---|---|---|
| Frontend | Next.js 15, React 19, TypeScript | Core framework and language for the application. |
| UI Components | Ant Design, @lobehub/ui, antd-style | Used for building the user interface. |
| State Mgmt | Zustand, SWR | For managing application state and data fetching. |
| Database | PostgreSQL, PGLite, Drizzle ORM | Database solutions and Object-Relational Mapping. |
| Testing | Vitest, Testing Library | Frameworks for unit and component testing. |
| Package Mgr | pnpm | Manages dependencies in the monorepo structure. |
| Build Tools | Next.js (Turbopack in dev, Webpack in prod) | Tools for building and bundling the application. |
| Runtime | bun | Used to run npm scripts. |
Sources: AGENTS.md:7-17, CLAUDE.md:20-21
Project Structure
The project utilizes a pnpm-based monorepo structure to organize its different parts. The main applications are located in the apps/ directory, while shared libraries and packages reside in the packages/ directory.
Sources: AGENTS.md:13, AGENTS.md:19-20
# pnpm-workspace.yaml
packages:
- 'apps/*'
- 'packages/*'
- 'examples/*'
Sources: pnpm-workspace.yaml:2-5
The following diagram illustrates the high-level directory structure.
This diagram shows the main directories within the monorepo, such as apps for applications and packages for shared code.
Sources: AGENTS.md:20-24, pnpm-workspace.yaml
Development Workflow
Developers should follow a standardized workflow for package management, Git usage, testing, and other development tasks to ensure consistency across the project.
Package Management
The project uses pnpm for dependency management and bun for running scripts.
| Command | Description |
|---|---|
pnpm i | Install dependencies across the monorepo. |
bun run ... | Execute an npm script. |
bunx ... | Run an executable npm package. |
Sources: AGENTS.md:33-36, CLAUDE.md:19-22
Git Workflow
A specific Git workflow is enforced to maintain a clean and understandable history. This includes branch naming conventions, commit message formatting, and the use of pull request templates.
The general flow is as follows:
This flowchart outlines the key steps for contributing code, from branch creation to submitting a pull request.
Sources: AGENTS.md:28-31, CLAUDE.md:15-18
Testing
Testing is a critical part of the development process. All new code must be accompanied by tests. The project uses vitest for running tests.
Key Commands:
- Web App Tests:
bunx vitest run --silent='passed-only' '[file-path-pattern]' - Package Tests:
cd packages/[package-name] && bunx vitest run --silent='passed-only' '[file-path-pattern]'
Important Rules:
- Never run
bun run test, as it runs all tests and is very time-consuming. - File paths in commands should be wrapped in single quotes.
- If a test fails twice after attempting a fix, it is recommended to seek help.
Sources: AGENTS.md:50-61, CLAUDE.md:33-42
A typical testing sequence for Clerk authentication is detailed in TESTING_CLERK_AUTH.md, which involves verifying user creation, sign-in, and protected route access.
This sequence diagram shows the flow for a new user signing up via Google OAuth and the subsequent webhook interaction that creates the user in the database.
Sources: TESTING_CLERK_AUTH.md
Internationalization (i18n)
The application supports multiple languages. The workflow for adding or updating translations is as follows:
- Add Keys: New translation keys must be added to the default locale files located at
src/locales/default/. For example,src/locales/default/discover.ts. - Translate: For development preview, translate the corresponding
zh-CNJSON file, such aslocales/zh-CN/discover.json. - Structure: Use hierarchical nested objects for keys, not flat keys.
- CI/CD: Do not run
pnpm i18nmanually. This process is handled automatically by the CI pipeline.
Sources: AGENTS.md:65-69, CLAUDE.md:46-49, src/locales/default/discover.ts
Documentation Workflow
The project's wiki documentation, located in the contributing/ directory, is automatically updated. A script aggregates markdown files to generate the Home.md and _Sidebar.md pages for the wiki.
// scripts/docsWorkflow/const.ts
export const WIKI_URL = 'https://github.com/lobehub/lobe-chat/wiki/%27%3B
export const ROOT = resolve(__dirname, '../..');
export const DOCS_DIR = resolve(ROOT, 'contributing');
export const HOME_PATH = resolve(DOCS_DIR, 'Home.md');
export const SIDEBAR_PATH = resolve(DOCS_DIR, '_Sidebar.md');
Sources: scripts/docsWorkflow/const.ts:4-8
The workflow script at scripts/docsWorkflow/index.ts reads the table of contents, finds all relevant markdown files, and generates links for both English and Chinese versions of the documents.
Sources: scripts/docsWorkflow/index.ts
Development Rules & Best Practices
The project maintains a set of development rules and guidelines in the .cursor/rules/ directory. These cover a wide range of topics from backend architecture to testing strategies.
| Rule File | Description |
|---|---|
backend-architecture.mdc | Three-layer architecture and data flow. |
react-component.mdc | Component patterns and UI library usage. |
drizzle-schema-style-guide.mdc | Database schema conventions. |
define-database-model.mdc | Model templates and CRUD patterns. |
i18n.mdc | Internationalization workflow. |
zustand-slice-organization.mdc | Store organization patterns. |
testing-guide/testing-guide.mdc | Comprehensive testing strategy. |
desktop-feature-implementation.mdc | Main/renderer process patterns for Electron. |
Sources: AGENTS.md:73-98, CLAUDE.md:53-78
Key best practices include:
- Code Language: Use Chinese for files with existing Chinese comments to maintain consistency. Use American English for all new files.
- Code Style: Be conservative with existing code but adopt modern approaches for new features.
- Testing: Always add tests for new functionality.
Sources: AGENTS.md:101-104, CLAUDE.md:25-29