第 6 课：Monorepo

┌─────────────────────────────────────────────────────────────────┐
│  🎯 核心观点：项目架构决定了 AI 的效率                           │
├─────────────────────────────────────────────────────────────────┤
│  📚 你将学到：                                                   │
│    • 理解传统项目结构对 AI 的三大困境                             │
│    • 掌握 Turborepo + pnpm workspace 的 Monorepo 方案            │
│    • 学习功能切片（Feature Slicing）的代码组织方式               │
│    • 掌握 AGENTS.md / .cursorrules 等项目规范文件的编写          │
│    • 横向对比 Turborepo、Nx、Lerna 等 Monorepo 工具             │
└─────────────────────────────────────────────────────────────────┘

src/
├── components/
│   ├── Button.tsx
│   ├── Modal.tsx
│   ├── UserAvatar.tsx
│   └── OrderCard.tsx
├── hooks/
│   ├── useAuth.ts
│   ├── useOrder.ts
│   └── useUser.ts
├── services/
│   ├── authService.ts
│   ├── orderService.ts
│   └── userService.ts
├── store/
│   ├── authSlice.ts
│   ├── orderSlice.ts
│   └── userSlice.ts
└── pages/
    ├── LoginPage.tsx
    ├── OrderPage.tsx
    └── UserProfilePage.tsx

src/
├── App.tsx (3000 行)
├── utils.ts (2000 行)
├── api.ts (1500 行)
├── types.ts (1000 行)
└── ... (100+ 个文件)

repo-1: frontend-main/
repo-2: frontend-admin/
repo-3: frontend-mobile/
repo-4: shared-components/
repo-5: shared-utils/

my-project/
├── apps/
│   ├── web/              # 主站
│   ├── admin/            # 管理后台
│   └── mobile/           # 移动端 H5
├── packages/
│   ├── ui/               # UI 组件库
│   ├── utils/            # 工具函数
│   ├── config/           # 共享配置
│   └── types/            # 类型定义
├── package.json
├── pnpm-workspace.yaml
└── turbo.json

src/
├── components/
│   ├── UserAvatar.tsx
│   ├── OrderCard.tsx
│   └── ProductCard.tsx
├── hooks/
│   ├── useUser.ts
│   ├── useOrder.ts
│   └── useProduct.ts
└── services/
    ├── userService.ts
    ├── orderService.ts
    └── productService.ts

src/
├── features/
│   ├── user/
│   │   ├── components/
│   │   │   └── UserAvatar.tsx
│   │   ├── hooks/
│   │   │   └── useUser.ts
│   │   ├── services/
│   │   │   └── userService.ts
│   │   └── index.ts
│   ├── order/
│   │   ├── components/
│   │   │   └── OrderCard.tsx
│   │   ├── hooks/
│   │   │   └── useOrder.ts
│   │   ├── services/
│   │   │   └── orderService.ts
│   │   └── index.ts
│   └── product/
│       ├── components/
│       │   └── ProductCard.tsx
│       ├── hooks/
│       │   └── useProduct.ts
│       ├── services/
│       │   └── productService.ts
│       └── index.ts

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    }
  }
}

# 登录 Vercel（Turborepo 的官方缓存服务）
npx turbo login

# 链接到你的项目
npx turbo link

{
  "dependencies": {
    "@myproject/ui": "1.0.0"
  }
}

{
  "dependencies": {
    "@myproject/ui": "workspace:*"
  }
}

packages:
  - 'apps/*'
  - 'packages/*'

{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint"
  },
  "devDependencies": {
    "turbo": "^2.0.0"
  }
}

{
  "name": "@myproject/ui",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
  }
}

{
  "name": "web",
  "version": "1.0.0",
  "dependencies": {
    "@myproject/ui": "workspace:*",
    "react": "^18.3.0",
    "next": "^15.0.0"
  }
}

pnpm install
pnpm build
pnpm dev

utils.ts
userAuthenticationHelpers.ts

# ❌ 不好的命名
Button.tsx
Modal.tsx
Card.tsx

# ✅ 好的命名
Button.tsx              # 基础组件可以简单命名
UserProfileCard.tsx     # 业务组件应该包含业务含义
OrderConfirmModal.tsx   # 清楚地表达用途

# ❌ 不好的命名
useData.ts
useFetch.ts

# ✅ 好的命名
useUserProfile.ts       # 清楚地表达获取什么数据
useOrderList.ts         # 业务含义明确
useAuthToken.ts         # 功能清晰

# ❌ 不好的命名
utils/
├── index.ts            # 什么都有

# ✅ 好的命名
utils/
├── date/
│   ├── formatDate.ts
│   └── parseDate.ts
├── string/
│   ├── capitalize.ts
│   └── truncate.ts
└── validation/
    ├── validateEmail.ts
    └── validatePhone.ts

packages/
├── features/           # 业务功能
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   ├── types/
│   │   └── index.ts
│   ├── order/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   ├── types/
│   │   └── index.ts
│   └── user/
│       ├── components/
│       ├── hooks/
│       ├── services/
│       ├── types/
│       └── index.ts
├── ui/                 # 通用 UI 组件
│   ├── Button/
│   ├── Input/
│   └── Modal/
├── utils/              # 通用工具函数
│   ├── date/
│   ├── string/
│   └── validation/
└── config/             # 配置文件
    ├── api.ts
    └── constants.ts

# AI Agent Instructions

## Project Overview
This is an e-commerce platform built with Next.js, React, and TypeScript.

## Architecture
- Monorepo managed by Turborepo + pnpm workspace
- Feature-sliced design: code organized by business features
- Shared packages: ui, utils, config, types

## Code Organization
- `apps/web`: Main website
- `apps/admin`: Admin dashboard
- `packages/features/*`: Business features (auth, order, user, product)
- `packages/ui`: Shared UI components
- `packages/utils`: Utility functions

## Naming Conventions
- Components: PascalCase (e.g., UserProfileCard.tsx)
- Hooks: camelCase with 'use' prefix (e.g., useUserProfile.ts)
- Utils: camelCase (e.g., formatDate.ts)
- Types: PascalCase with 'Type' or 'Interface' suffix

## Code Style
- Use TypeScript strict mode
- Prefer functional components with hooks
- Use Tailwind CSS for styling
- Follow ESLint and Prettier rules

## When Adding New Features
1. Create a new directory under `packages/features/`
2. Include: components/, hooks/, services/, types/, index.ts
3. Export public APIs through index.ts
4. Add dependencies in package.json with workspace protocol

## Testing
- Unit tests: Vitest
- E2E tests: Playwright
- Test files: *.test.ts or *.spec.ts

## Project Overview
E-commerce platform for B2B wholesale market.
Tech stack: Next.js 15, React 19, TypeScript 5.5, Tailwind CSS v4, Prisma ORM.
Database: PostgreSQL. Cache: Redis. Search: Elasticsearch.

## Architecture
- Monorepo: Turborepo + pnpm workspace
- Frontend: Next.js App Router with RSC (React Server Components)
- API: Next.js Route Handlers + tRPC
- Auth: NextAuth.js v5
- State: Zustand for client state, React Query for server state

## Code Conventions
- Always use TypeScript strict mode
- Prefer 'interface' over 'type' for object shapes
- Use named exports, avoid default exports
- Component files: one component per file
- Max file length: 300 lines (split if longer)
- Error handling: use Result pattern, avoid try-catch in business logic

## Do NOT
- Do NOT use `any` type
- Do NOT use `var`, always use `const` or `let`
- Do NOT use CSS modules, use Tailwind CSS
- Do NOT use class components
- Do NOT import from internal paths of packages, use public API only
- Do NOT add new dependencies without discussing first

## Common Tasks

### Adding a new API endpoint
1. Create route handler in `apps/web/app/api/[resource]/route.ts`
2. Define input/output types in `packages/types/api/`
3. Add validation with Zod schema
4. Write unit test in `__tests__/` directory

### Adding a new UI component
1. Create component in `packages/ui/src/[ComponentName]/`
2. Include: ComponentName.tsx, ComponentName.test.tsx, index.ts
3. Export from `packages/ui/src/index.ts`
4. Add Storybook story if it's a visual component

You are an expert in TypeScript, React, Next.js, and Tailwind CSS.

Key Principles:
- Write concise, technical TypeScript code with accurate examples
- Use functional and declarative programming patterns; avoid classes
- Prefer iteration and modularization over code duplication
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError)

Project Structure:
- This is a Turborepo monorepo with pnpm workspace
- apps/web: Next.js 15 with App Router
- packages/ui: Shared React components
- packages/features: Business logic organized by feature

TypeScript:
- Use TypeScript for all code; prefer interfaces over types
- Avoid enums; use const objects with 'as const'
- Use functional components with TypeScript interfaces for props

React:
- Use functional components with hooks
- Minimize 'use client'; prefer React Server Components
- Wrap client components in Suspense with fallback
- Use dynamic loading for non-critical components

Styling:
- Use Tailwind CSS v4 for all styling
- Use cn() utility for conditional classes
- Follow mobile-first responsive design

State Management:
- URL state: nuqs for search params
- Client state: Zustand
- Server state: React Query (TanStack Query)

Error Handling:
- Use error boundaries for unexpected errors
- Model expected errors as return values
- Use useActionState for form validation
- Always provide user-friendly error messages

# CLAUDE.md

## Project
B2B e-commerce platform monorepo.

## Quick Reference
- Build: `pnpm build`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Type check: `pnpm typecheck`

## Architecture Decisions
- We use App Router, NOT Pages Router
- We use Server Components by default, 'use client' only when needed
- We use Zustand for client state, NOT Redux
- We use Prisma, NOT TypeORM or Drizzle

## Current Sprint Focus
- Implementing order management module
- Refactoring auth flow to support SSO
- Performance optimization for product listing page

## Known Issues
- Hot reload sometimes fails in packages/ui, restart dev server
- Prisma client needs regeneration after schema changes: `pnpm db:generate`

my-project/
├── AGENTS.md                    # 项目级：整体架构和约定
├── apps/
│   ├── web/
│   │   └── AGENTS.md            # 应用级：Web 应用的特定约定
│   └── admin/
│       └── AGENTS.md            # 应用级：Admin 应用的特定约定
└── packages/
    ├── ui/
    │   └── AGENTS.md            # 包级：UI 组件的开发规范
    └── features/
        └── order/
            └── AGENTS.md        # 功能级：订单模块的业务规则

# 使用 Turborepo 官方模板创建项目
pnpm dlx create-turbo@latest my-ai-friendly-project

# 进入项目目录
cd my-ai-friendly-project

my-ai-friendly-project/
├── apps/
│   ├── web/              # Next.js 应用
│   └── docs/             # 文档站点
├── packages/
│   ├── ui/               # 共享 UI 组件
│   ├── eslint-config/    # ESLint 配置
│   └── typescript-config/ # TypeScript 配置
├── package.json
├── pnpm-workspace.yaml
└── turbo.json

# 创建 features 目录
mkdir -p packages/features/auth/{components,hooks,services,types}
mkdir -p packages/features/order/{components,hooks,services,types}
mkdir -p packages/features/user/{components,hooks,services,types}

# AI Agent Instructions

## Project Overview
This is a demo e-commerce platform built with Turborepo + pnpm workspace.

## Tech Stack
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.5 (strict mode)
- Styling: Tailwind CSS v4
- State: Zustand + React Query
- Testing: Vitest + Playwright

## Monorepo Structure
- apps/web: Main website (Next.js)
- apps/docs: Documentation (Next.js)
- packages/ui: Shared UI components
- packages/features/auth: Authentication feature
- packages/features/order: Order management feature
- packages/features/user: User management feature

## Conventions
- Use functional components with hooks
- One component per file
- Named exports only
- Tailwind CSS for styling (no CSS modules)
- Zod for validation
- Error boundaries for error handling

## Commands
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

You are an expert in TypeScript, React, Next.js, and Tailwind CSS.

This is a Turborepo monorepo. When modifying code:
1. Check which package the file belongs to
2. Respect package boundaries - import through public API (index.ts)
3. Use workspace protocol for internal dependencies
4. Follow the naming conventions in AGENTS.md

When creating new features:
1. Create under packages/features/[feature-name]/
2. Include: components/, hooks/, services/, types/, index.ts
3. Export public API through index.ts
4. Add package.json with workspace dependencies