mirror of
https://github.com/lobehub/lobehub
synced 2026-04-21 17:47:27 +00:00
98 lines
3.4 KiB
Markdown
98 lines
3.4 KiB
Markdown
# LobeHub Development Guidelines
|
|
|
|
This document serves as a comprehensive guide for all team members when developing LobeHub.
|
|
|
|
## Project Description
|
|
|
|
You are developing an open-source, modern-design AI Agent Workspace: LobeHub (previously LobeChat).
|
|
|
|
## Tech Stack
|
|
|
|
- **Frontend**: Next.js 16, React 19, TypeScript
|
|
- **UI Components**: Ant Design, @lobehub/ui, antd-style
|
|
- **State Management**: Zustand, SWR
|
|
- **Database**: PostgreSQL, PGLite, Drizzle ORM
|
|
- **Testing**: Vitest, Testing Library
|
|
- **Package Manager**: pnpm (monorepo structure)
|
|
|
|
## Directory Structure
|
|
|
|
```plaintext
|
|
lobehub/
|
|
├── apps/desktop/ # Electron desktop app
|
|
├── packages/ # Shared packages (@lobechat/*)
|
|
│ ├── database/ # Database schemas, models, repositories
|
|
│ ├── agent-runtime/ # Agent runtime
|
|
│ └── ...
|
|
├── src/
|
|
│ ├── app/ # Next.js app router
|
|
│ ├── spa/ # SPA entry points (entry.*.tsx) and router config
|
|
│ ├── routes/ # SPA page components (roots)
|
|
│ ├── features/ # Business components by domain
|
|
│ ├── store/ # Zustand stores
|
|
│ ├── services/ # Client services
|
|
│ ├── server/ # Server services and routers
|
|
│ └── ...
|
|
├── .agents/skills/ # AI development skills
|
|
└── e2e/ # E2E tests (Cucumber + Playwright)
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Git Workflow
|
|
|
|
- **Branch strategy**: `canary` is the development branch (cloud production); `main` is the release branch (periodically cherry-picks from canary)
|
|
- New branches should be created from `canary`; PRs should target `canary`
|
|
- Use rebase for git pull
|
|
- Git commit messages should prefix with gitmoji
|
|
- Git branch name format: `feat/feature-name`
|
|
- Use `.github/PULL_REQUEST_TEMPLATE.md` for PR descriptions
|
|
|
|
### Package Management
|
|
|
|
- Use `pnpm` as the primary package manager
|
|
- Use `bun` to run npm scripts
|
|
- Use `bunx` to run executable npm packages
|
|
|
|
### Code Style Guidelines
|
|
|
|
#### TypeScript
|
|
|
|
- Prefer interfaces over types for object shapes
|
|
|
|
### Testing Strategy
|
|
|
|
```bash
|
|
# Web tests
|
|
bunx vitest run --silent='passed-only' '[file-path-pattern]'
|
|
|
|
# Package tests (e.g., database)
|
|
cd packages/[package-name] && bunx vitest run --silent='passed-only' '[file-path-pattern]'
|
|
```
|
|
|
|
**Important Notes**:
|
|
|
|
- Wrap file paths in single quotes to avoid shell expansion
|
|
- Never run `bun run test` - this runs all tests and takes \~10 minutes
|
|
|
|
### Type Checking
|
|
|
|
- Use `bun run type-check` to check for type errors
|
|
|
|
### i18n
|
|
|
|
- **Keys**: Add to `src/locales/default/namespace.ts`
|
|
- **Dev**: Translate `locales/zh-CN/namespace.json` locale file only for preview
|
|
- DON'T run `pnpm i18n`, let CI auto handle it
|
|
|
|
## SPA Routes and Features
|
|
|
|
- **`src/routes/`** holds only page segments (`_layout/index.tsx`, `index.tsx`, `[id]/index.tsx`). Keep route files **thin** — import from `@/features/*` and compose, no business logic.
|
|
- **`src/features/`** holds business components by **domain** (e.g. `Pages`, `PageEditor`, `Home`). Layout pieces, hooks, and domain UI go here.
|
|
- See the **spa-routes** skill for the full convention and file-division rules.
|
|
|
|
## Skills (Auto-loaded)
|
|
|
|
All AI development skills are available in `.agents/skills/` directory and auto-loaded by Claude Code when relevant.
|
|
|
|
**IMPORTANT**: When reviewing PRs or code diffs, ALWAYS read `.agents/skills/code-review/SKILL.md` first.
|