lobehub/CLAUDE.md

CLAUDE.md

Guidelines for using Claude Code in this LobeHub repository.

Tech Stack

• Next.js 16 + React 19 + TypeScript
• SPA inside Next.js with react-router-dom
• @lobehub/ui, antd for components; antd-style for CSS-in-JS
• react-i18next for i18n; zustand for state management
• SWR for data fetching; TRPC for type-safe backend
• Drizzle ORM with PostgreSQL; Vitest for testing

Project Structure

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 (backend API + auth)
│   │   ├── (backend)/     # API routes (trpc, webapi, etc.)
│   │   ├── spa/            # SPA HTML template service
│   │   └── [variants]/(auth)/  # Auth pages (SSR required)
│   ├── routes/             # SPA page components (Vite)
│   │   ├── (main)/         # Desktop pages
│   │   ├── (mobile)/       # Mobile pages
│   │   ├── (desktop)/      # Desktop-specific pages
│   │   ├── onboarding/     # Onboarding pages
│   │   └── share/          # Share pages
│   ├── spa/                # SPA entry points and router config
│   │   ├── entry.web.tsx   # Web entry
│   │   ├── entry.mobile.tsx
│   │   ├── entry.desktop.tsx
│   │   └── router/         # React Router configuration
│   ├── store/              # Zustand stores
│   ├── services/           # Client services
│   ├── server/             # Server services and routers
│   └── ...
└── e2e/                    # E2E tests (Cucumber + Playwright)

SPA Routes and Features

SPA-related code is grouped under src/spa/ (entries + router) and src/routes/ (page segments). We use a roots vs features split: route trees only hold page segments; business logic and UI live in features.

• src/spa/ – SPA entry points (entry.web.tsx, entry.mobile.tsx, entry.desktop.tsx) and React Router config (router/). Keeps router config next to entries to avoid confusion with src/routes/.

• src/routes/ (roots)
  Only page-segment files: _layout/index.tsx, index.tsx (or page.tsx), and dynamic segments like [id]/index.tsx. Keep these thin: they should only import from @/features/* and compose layout/page, with no business logic or heavy UI.

• src/features/
  Business components by domain (e.g. Pages, PageEditor, Home). Put layout chunks (sidebar, header, body), hooks, and domain-specific UI here. Each feature exposes an index.ts (or index.tsx) with clear exports.

When adding or changing SPA routes:

1. In src/routes/, add only the route segment files (layout + page) that delegate to features.
2. Implement layout and page content under src/features/<Domain>/ and export from there.
3. In route files, use import { X } from '@/features/<Domain>' (or import Y from '@/features/<Domain>/...'). Do not add new features/ folders inside src/routes/.

See the spa-routes skill (.agents/skills/spa-routes/SKILL.md) for the full convention and file-division rules.

Development

Starting the Dev Environment

# SPA dev mode (frontend only, proxies API to localhost:3010)
bun run dev:spa

# Full-stack dev (Next.js + Vite SPA concurrently)
bun run dev

After dev:spa starts, the terminal prints a Debug Proxy URL:

Debug Proxy: https://app.lobehub.com/_dangerous_local_dev_proxy?debug-host=http%3A%2F%2Flocalhost%3A9876

Open this URL to develop locally against the production backend (app.lobehub.com). The proxy page loads your local Vite dev server's SPA into the online environment, enabling HMR with real server config.

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
• Commit messages: prefix with gitmoji
• Branch format: <type>/<feature-name>

Package Management

• pnpm for dependency management
• bun to run npm scripts
• bunx for executable npm packages

Testing

# Run specific test (NEVER run `bun run test` - takes ~10 minutes)
bunx vitest run --silent='passed-only' '[file-path]'

# Database package
cd packages/database && bunx vitest run --silent='passed-only' '[file]'

• Prefer vi.spyOn over vi.mock
• Tests must pass type check: bun run type-check
• After 2 failed fix attempts, stop and ask for help

i18n

• Add keys to src/locales/default/namespace.ts
• For dev preview: translate locales/zh-CN/ and locales/en-US/
• Don't run pnpm i18n - CI handles it

Skills (Auto-loaded by Claude)

Claude Code automatically loads relevant skills from .agents/skills/.