This document describes the build system, package management, development workflow, and local setup procedures for LobeChat. For deployment configurations, see Docker Build and Multi-Stage Pipeline, Self-Hosting with Docker Compose, Cloud Deployment on Vercel, and Desktop Application Distribution. For CI/CD automation, see CI/CD and Release Process.
LobeChat uses pnpm 10.20.0 as its package manager with workspace support for monorepo architecture. The root package.json1-464 defines workspace configurations that organize the codebase into multiple packages.
Workspace Members (package.json28-33):
packages/* - Core runtime, database, and utility packagespackages/business/* - Business logic packagese2e - End-to-end test suiteapps/desktop/src/main - Desktop application main processSources: package.json28-33
Create a .env.local file in the root directory with required environment variables:
For complete environment variable reference, see Environment Variables Reference.
Sources: package.json1-464
| Command | Description | Port | Use Case |
|---|---|---|---|
pnpm dev | Start web dev server | 3010 | Standard web development |
pnpm dev:bun | Start with Bun runtime | 3010 | Alternative runtime |
pnpm dev:desktop | Desktop app dev mode | 3015 | Desktop-specific features |
pnpm dev:mobile | Mobile-optimized dev | 3018 | Mobile UI testing |
Development Server Startup Flow:
Sources: package.json55-59
Desktop development requires additional setup:
The desktop development process (package.json57-58):
NEXT_PUBLIC_IS_DESKTOP_APP=1 environment variablescripts/runNextDesktop.mtsSources: package.json57-58
LobeChat supports three primary build targets:
Sources: package.json36-54 next.config.ts1-32
Web Build (package.json36-42):
Desktop Build (package.json49-54):
Build Process Flow:
Sources: package.json35-43
The build system uses a custom Next.js configuration builder at src/libs/next/config/define-config.ts1-420
Configuration Features (src/libs/next/config/define-config.ts18-419):
Standalone Mode Detection (src/libs/next/config/define-config.ts28-33):
NEXT_BUILD_STANDALONE=1Build Optimizations (next.config.ts6-9):
webpackBuildWorker: true - Parallel webpack buildswebpackMemoryOptimizations: true - Memory efficiencyOutput File Tracing (next.config.ts13-20):
Sources: src/libs/next/config/define-config.ts18-34 next.config.ts1-32
LobeChat enforces comprehensive code quality checks:
lint-staged Configuration (package.json110-136):
Linting Commands (package.json69-78):
Sources: package.json69-78 package.json110-136
The build system includes circular dependency checks using dpdm:
Detection Configuration (package.json71-72):
dpdm with exit code on circular dependenciesSources: package.json71-72
LobeChat uses Drizzle ORM for database schema management and migrations.
Database Scripts (package.json45-48):
| Command | Description | Usage |
|---|---|---|
pnpm db:generate | Generate migrations from schema | After schema changes |
pnpm db:migrate | Run pending migrations | Deployment or setup |
pnpm db:studio | Launch Drizzle Studio | Visual database management |
pnpm db:visualize | Generate DBML docs | Schema documentation |
Migration Workflow:
Migration Script Location: scripts/migrateServerDB/index.ts runs during build (package.json46).
Sources: package.json45-48
Testing Commands (package.json90-95):
Sources: package.json90-95 codecov.yml1-41
Coverage configuration is defined in codecov.yml1-41:
Component-Based Coverage (codecov.yml2-23):
app_store - State management (src/store/*)app_services - Service layer (src/services/*)app_server - Server code (src/server/*)app_libs - Shared libraries (src/libs/*)app_utils - Utility functions (src/utils/*)Coverage Flags (codecov.yml25-36):
database - Database package testsapp - Application tests with 50% thresholdSources: codecov.yml1-41
LobeChat maintains 13+ languages with automated translation workflows.
i18n Scripts (package.json66-68):
Translation Pipeline:
Automated Translation (package.json66):
workflow:i18n script to process default localelobe-i18n CLI with OpenAI integrationSources: package.json66-68
The changelog system maintains version history across multiple formats.
Changelog Scripts (package.json100):
Changelog Architecture:
Changelog File Structure (scripts/changelogWorkflow/const.ts1-13):
CHANGELOG.md - Current version (v2.x)changelog/CHANGELOG.v1.md - Version 1.x archivechangelog/CHANGELOG.v0.md - Version 0.x archivedocs/changelog/ - Formatted MDX postsdocs/changelog/index.json - Version index with metadataIndex Format (docs/changelog/index.json1-181):
Sources: package.json100 scripts/changelogWorkflow/const.ts1-13 docs/changelog/index.json1-181
The build system includes automated image optimization for documentation.
CDN Workflow (package.json99 scripts/cdnWorkflow/index.ts1-230):
CDN Configuration (scripts/cdnWorkflow/index.ts20-32):
.cdn.cache.jsonDOC_S3_PUBLIC_DOMAIN environment variableSources: package.json99 scripts/cdnWorkflow/index.ts1-230
The build system defines specific package version overrides:
Version Locks (package.json137-140 package.json458-463):
These overrides ensure:
Sources: package.json137-140 package.json458-463
The monorepo includes 50+ internal packages referenced via workspace:* protocol:
Core Workspace Packages (package.json166-200):
@lobechat/agent-runtime - AI agent execution@lobechat/model-runtime - Model provider integration@lobechat/database - Database layer@lobechat/builtin-tool-* - Built-in tool packages (10+)@lobechat/business-* - Business logic packagesSources: package.json166-200
Development Tunneling Flow:
Sources: package.json96-97 package.json82
The reinstall script (package.json83) removes:
.next directorynode_modules in root and packagespnpm installSources: package.json83-84 package.json44
Docker Build Features (package.json86-87):
lobehub:local by defaultUSE_CN_MIRROR=true for China-based dependenciesSources: package.json86-87
| Category | Command | Purpose |
|---|---|---|
| Development | pnpm dev | Start development server |
pnpm dev:desktop | Desktop app development | |
| Building | pnpm build | Production build |
pnpm build:docker | Docker-optimized build | |
pnpm desktop:build | Desktop application build | |
| Quality | pnpm lint | Run all linters |
pnpm type-check | TypeScript validation | |
pnpm test | Run test suites | |
| Database | pnpm db:generate | Generate migrations |
pnpm db:migrate | Apply migrations | |
pnpm db:studio | Launch database UI | |
| Content | pnpm i18n | Update translations |
pnpm workflow:changelog | Generate changelog | |
pnpm workflow:cdn | Optimize images | |
| Maintenance | pnpm reinstall | Clean reinstall |
pnpm lint:unused | Find unused code |
Sources: package.json34-109
Refresh this wiki