mirror of
https://github.com/lobehub/lobehub.git
synced 2026-03-26 13:19:34 +07:00
463d6c8762
* 🔧 chore(vscode): add typescript.tsdk and disable mdx server Fix MDX extension crash caused by Cursor's bundled TypeScript version * 🔧 chore(claude): add skills symlink to .claude directory * 📝 docs: update development guides with current tech stack and architecture - Update tech stack: Next.js 16 + React 19, hybrid routing (App Router + React Router DOM), tRPC, Drizzle ORM + PostgreSQL, react-i18next - Update directory structure to reflect monorepo layout (apps/, packages/, e2e/, locales/) - Expand src/server/ with detailed subdirectory descriptions - Add complete SPA routing architecture with desktop and mobile route tables - Add tRPC router grouping details (lambda, async, tools, mobile) - Add data flow diagram - Simplify dev setup section to link to setup-development guide - Fix i18n default language description (English, not Chinese) - Sync all changes between zh-CN and English versions * 📝 docs: expand data flow diagram in folder structure guide Replace the single-line data flow with a detailed layer-by-layer flow diagram showing each layer's location and responsibility. * 📝 docs: modernize feature development guide - Remove outdated clientDB/pglite/indexDB references - Update schema path to packages/database/src/schemas/ - Update types path to packages/types/src/ - Replace inline migration steps with link to db-migrations guide - Add complete layered architecture table (Client Service, WebAPI, tRPC Router, Server Service, Server Module, Repository, DB Model) - Clarify Client Service as frontend code - Add i18n handling section with workflow and key naming convention - Remove verbose CSS style code, keep core business logic only - Expand testing section with commands, skill refs, and CI tip * 🔥 docs: remove outdated frontend feature development guide Content is superseded by the comprehensive feature-development guide which covers the full chain from schema to testing. * 📝 docs: add LobeHub ecosystem and community resources Add official ecosystem packages (LobeUI, LobeIcons, LobeCharts, LobeEditor, LobeTTS, LobeLint, Lobe i18n, MCP Mark) and community platforms (Agent Market, MCP Market, YouTube, X, Discord). * 📝 docs: improve contributing guidelines and resources - Clarify semantic release triggers (feat/fix vs style/chore) - Add testing section with Vitest/E2E/CI requirements - Update contribution steps to include CI check - Add LobeHub ecosystem packages and community platforms to resources * 📝 docs: rewrite architecture guide to reflect current platform design * 📝 docs: add code quality tools to architecture guide * 📝 docs: rewrite chat-api guide to reflect current architecture - Update sequence diagram with Agent Runtime loop as core execution engine - Replace PluginGateway with ToolExecution layer (Builtin/MCP/Plugin) - Update all path references (model-runtime, agent-runtime, fetch-sse packages) - Split old AgentRuntime section into Model Runtime + Agent Runtime - Add tool calling taxonomy: Builtin, MCP, and Plugin (deprecated) - Add client-side vs server-side execution section - Remove outdated adapter pseudo-code examples * 📝 docs: update file paths in add-new-image-model guide - src/libs/standard-parameters/ → packages/model-bank/src/standard-parameters/ - src/config/aiModels/ → packages/model-bank/src/aiModels/ - src/libs/model-runtime/ → packages/model-runtime/src/providers/ * 📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides The S3_PUBLIC_DOMAIN env var was incorrectly removed from all documentation in commit4a87b31. This variable is still required by the code (src/server/services/file/impls/s3.ts) to generate public URLs for uploaded files. Without it, image URLs sent to vision models are just S3 keys instead of full URLs. Closes #12161 * 📦 chore: pin @lobehub/ui to 4.33.4 to fix SortableList type errors @lobehub/ui 4.34.0 introduced breaking type changes in SortableList where SortableListItem became strict, causing type incompatibility in onChange and renderItem callbacks across 6 files. Pin to 4.33.4 via pnpm overrides to enforce consistent version across monorepo. * 🐛 fix: correct ReadableStream type annotations and add dom.asynciterable - Add dom.asynciterable to tsconfig lib for ReadableStream async iteration - Fix createCallbacksTransformer return type: TransformStream<string, Uint8Array> - Update stream function return types from ReadableStream<string> to ReadableStream<Uint8Array> (llama.ts, ollama.ts, claude.ts) - Remove @ts-ignore from for-await loops in test files - Add explicit string[] type for chunks arrays * Revert "📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides" This reverts commit24073f83d3.
113 lines
7.3 KiB
Plaintext
113 lines
7.3 KiB
Plaintext
---
|
|
title: Technical Development Getting Started Guide
|
|
description: >-
|
|
Explore the LobeHub development setup, technology stack, and contribution
|
|
guidelines.
|
|
tags:
|
|
- LobeHub
|
|
- Next.js
|
|
- Development Guide
|
|
- Internationalization
|
|
- Open Source
|
|
---
|
|
|
|
# Technical Development Getting Started Guide
|
|
|
|
Welcome to the LobeHub Technical Development Getting Started Guide. LobeHub is an AI conversation application built on the Next.js framework, incorporating a range of technology stacks to achieve diverse functionalities and features. This guide will detail the main technical components of LobeHub and how to configure and use these technologies in your development environment.
|
|
|
|
## Basic Technology Stack
|
|
|
|
The core technology stack of LobeHub is as follows:
|
|
|
|
- **Framework**: [Next.js](https://nextjs.org/) 16 + [React](https://react.dev/) 19, providing server-side rendering, Router Handler, and other key features.
|
|
- **Component Library**: [Ant Design (antd)](https://ant.design/) as the base component library, [@lobehub/ui](https://github.com/lobehub/lobe-ui) as the business component library.
|
|
- **State Management**: [zustand](https://github.com/pmndrs/zustand), a lightweight and easy-to-use state management library.
|
|
- **Data Fetching**: [SWR](https://swr.vercel.app/) for client-side data fetching.
|
|
- **Routing**: Hybrid routing architecture — [Next.js App Router](https://nextjs.org/) for static pages (e.g., auth pages), [React Router DOM](https://reactrouter.com/) for the main SPA.
|
|
- **API**: [tRPC](https://trpc.io/) for end-to-end type-safe API communication.
|
|
- **Database**: [Drizzle ORM](https://orm.drizzle.team/) + PostgreSQL.
|
|
- **Internationalization**: [react-i18next](https://react.i18next.com/) for multilingual support.
|
|
- **Styling**: [antd-style](https://github.com/ant-design/antd-style), a CSS-in-JS library that complements Ant Design.
|
|
- **Unit Testing**: [Vitest](https://github.com/vitest-dev/vitest) for unit testing.
|
|
|
|
## Folder Directory Structure
|
|
|
|
LobeHub uses a Monorepo architecture
|
|
(`@lobechat/` namespace).
|
|
The top-level directory structure is as follows:
|
|
|
|
```bash
|
|
lobe-chat/
|
|
├── apps/desktop/ # Electron desktop app
|
|
├── packages/ # Shared packages (@lobechat/*)
|
|
│ ├── database/ # Database schemas, models, repositories
|
|
│ ├── agent-runtime/ # Agent runtime
|
|
│ ├── model-runtime/ # Model runtime
|
|
│ └── ... # More shared packages
|
|
├── src/ # Main application source code
|
|
│ ├── app/ # Next.js App Router with route groups and API routes
|
|
│ ├── components/ # Reusable UI components
|
|
│ ├── config/ # App configuration, client and server env vars
|
|
│ ├── const/ # Application constants and enums
|
|
│ ├── envs/ # Env var definitions and validation (analytics, auth, LLM, etc.)
|
|
│ ├── features/ # Business feature modules (Agent settings, plugin dev, etc.)
|
|
│ ├── helpers/ # Utility helper functions
|
|
│ ├── hooks/ # Reusable custom Hooks
|
|
│ ├── layout/ # Layout components (AuthProvider, GlobalProvider, etc.)
|
|
│ ├── libs/ # Third-party integrations (better-auth, OIDC, tRPC, etc.)
|
|
│ ├── locales/ # Internationalization language files
|
|
│ ├── server/ # Server-side modules, routers, and services
|
|
│ ├── services/ # Client-side service interfaces
|
|
│ ├── store/ # Zustand state management
|
|
│ ├── styles/ # Global styles and CSS-in-JS configurations
|
|
│ ├── tools/ # Built-in tools (artifacts, inspectors, interventions, etc.)
|
|
│ ├── types/ # TypeScript type definitions
|
|
│ └── utils/ # General utility functions
|
|
├── locales/ # i18n translation files (zh-CN, en-US, etc.)
|
|
└── e2e/ # E2E tests (Cucumber + Playwright)
|
|
```
|
|
|
|
For a detailed introduction to the directory structure, see: [Folder Directory Structure](/docs/development/basic/folder-structure)
|
|
|
|
## Local Development Environment Setup
|
|
|
|
Please refer to the
|
|
[Environment Setup Guide](/docs/development/basic/setup-development)
|
|
for the complete setup process,
|
|
including software installation, project configuration,
|
|
Docker service startup, and database migrations.
|
|
|
|
## Code Style and Contribution Guide
|
|
|
|
In the LobeHub project, we place great emphasis on the quality and consistency of the code. For this reason, we have established a series of code style standards and contribution processes to ensure that every developer can smoothly participate in the project. Here are the code style and contribution guidelines you need to follow as a developer.
|
|
|
|
- **Code Style**: We use `@lobehub/lint` to unify the code style, including ESLint, Prettier, remarklint, and stylelint configurations. Please adhere to our code standards to maintain code consistency and readability.
|
|
- **Contribution Process**: We use gitmoji and semantic release for code submission and release processes. Please use gitmoji to annotate your commit messages and ensure compliance with the semantic release standards so that our automation systems can correctly handle version control and releases.
|
|
|
|
All contributions will undergo code review. Maintainers may suggest modifications or requirements. Please respond actively to review comments and make timely adjustments. We look forward to your participation and contribution.
|
|
|
|
For detailed code style and contribution guidelines, please refer to [Code Style and Contribution Guide](/docs/development/basic/contributing-guidelines).
|
|
|
|
## Internationalization Implementation Guide
|
|
|
|
LobeHub uses `react-i18next` for multilingual support,
|
|
ensuring a global user experience.
|
|
|
|
Default language files are located in `src/locales/default/`
|
|
(English). Translation files are in the `locales/` directory.
|
|
During development, you only need to edit keys in
|
|
`src/locales/default/` — CI automatically generates
|
|
translation files for other languages.
|
|
|
|
If you want to add a new language, follow specific steps detailed in [New Language Addition Guide](/docs/development/internationalization/add-new-locale). We encourage you to participate in our internationalization efforts to provide better services to global users.
|
|
|
|
For a detailed guide on internationalization implementation, please refer to [Internationalization Implementation Guide](/docs/development/internationalization/internationalization-implementation).
|
|
|
|
## Appendix: Resources and References
|
|
|
|
To support developers in better understanding and using the technology stack of LobeHub, we provide a comprehensive list of resources and references — [LobeHub Resources and References](/docs/development/basic/resources) - Visit our maintained list of resources, including tutorials, articles, and other useful links.
|
|
|
|
We encourage developers to utilize these resources to deepen their learning and enhance their skills, join community discussions through [LobeHub GitHub Discussions](https://github.com/lobehub/lobehub/discussions) or [Discord](https://discord.com/invite/AYFPHvv2jT), ask questions, or share your experiences.
|
|
|
|
If you have any questions or need further assistance, please do not hesitate to contact us through the above channels.
|