This guide provides technical contributors with a high-level overview of the LobeHub development environment, architecture, and standards. LobeHub is a monorepo built with a modern TypeScript stack, utilizing Next.js for the web application and Electron for the desktop experience.
LobeHub follows a monorepo structure using pnpm workspaces package.json35-40 The codebase is divided into apps/ for entry-point applications and packages/ for shared business logic and infrastructure.
apps/: Contains the primary deployment targets: desktop (Electron) package.json62 cli (LobeHub CLI), and the Next.js server.packages/: Shared libraries such as database (Drizzle schemas), agent-runtime, and model-bank vitest.config.mts15-26src/: The core application logic, including Next.js App Router for backend/auth and a Vite-powered SPA for the main chat interface package.json49-52LobeHub employs a "roots vs. features" architectural split for the SPA to maintain scalability:
src/routes/ (Roots): Contains thin page-segment files that delegate UI and logic to features.src/features/: Domain-specific business components (e.g., Conversation, AgentSetting, ShareModal) package.json97For details, see Project Structure and Conventions.
The development environment is orchestrated to support both local web development and desktop application testing.
LobeHub uses a custom startup sequence to manage concurrent processes.
npm run dev: Starts the full-stack environment via a startup script package.json69npm run dev:spa: Starts only the frontend Vite dev server package.json76npm run dev:docker: Provisions local infrastructure like PostgreSQL and Redis via Docker Compose package.json72The Next.js server typically runs on port 3010 package.json75 while the production start script defaults to port 3210 package.json109
For details, see Development Workflow.
The following diagram illustrates how natural language concepts map to specific code entities within the LobeHub repository.
Sources: package.json30-39 package.json57-59 tsconfig.json19-30
LobeHub follows a strict component priority and styling convention to ensure performance and consistency.
antd-style for theme-aware CSS-in-JS src/layout/SPAGlobalProvider/index.tsx4emotion for dynamic styles package.json110stylelint rules are applied to all TypeScript files to maintain visual consistency package.json96src/components: Project-specific reusables.@lobehub/ui: LobeHub's own design system components src/layout/SPAGlobalProvider/index.tsx3antd: Base UI components via antd-style integration.For details, see Contributing Guidelines.
The testing infrastructure ensures reliability across the monorepo and individual packages.
e2e/ workspace package.json82-84LobeHub uses v8 as the coverage provider and reports to Codecov vitest.config.mts118-120
For details, see Testing Strategy.
LobeHub provides tools for programmatic interaction and backend verification.
lh)The CLI (located in apps/cli) allows developers to manage agents and tasks from the terminal package.json55
The packages/openapi package provides a Hono-based REST API for external client integration.
For details, see CLI Tool (lh) and OpenAPI and External HTTP API.
LobeHub utilizes GitHub Actions for a comprehensive release pipeline.
semantic-release package.json105auto-i18n.yml) automatically handles missing translations across supported locales using the lobe-i18n tool .github/workflows/auto-i18n.yml35For details, see CI/CD Workflows.
Sources: src/layout/SPAGlobalProvider/index.tsx51-55 vitest.config.mts15-18 package.json75-76
Refresh this wiki