React 项目开发全流程指南（中文）。涵盖技术栈选型、Monorepo 架构（pnpm + Turborepo）、开发规范、Git 提交约定、Changelog 管理、测试策略、代码审查、开发工作流与文档管理。适用于 React + TypeScript + Zustand + TanStack Query + Vitest + Playwright 技术栈。当用户创建 React 项目、编写/审查/重构 React 代码、配置测试或 CI/CD、创建需求/设计文档时自动激活。
| 领域 | 选型 | 理由 |
|---|---|---|
| 语言 | TypeScript 5.x（strict mode） | 类型安全，减少运行时错误 |
| UI 框架 | React 18/19 | 生态成熟，社区活跃 |
| 包管理 | pnpm | workspace 原生支持，磁盘效率高，严格依赖隔离 |
| Monorepo | Turborepo | 增量构建、任务编排、远程缓存，与 pnpm 深度集成 |
| 客户端状态 | Zustand | 轻量（~1KB），API 简洁，无 Provider 嵌套 |
| 服务端状态 | TanStack Query | 缓存、重试、乐观更新、后台刷新一站式解决 |
| 路由 | React Router v7 | 通用 SPA 路由，类型安全，数据加载内置 |
| 样式 | Tailwind CSS + CSS Modules | 原子化 CSS 提效 + 模块化隔离 |
| 表单 | React Hook Form + Zod | 非受控高性能 + schema 验证复用 |
| HTTP | Axios / ky | 拦截器、取消请求，配合 TanStack Query |
| 构建 | Vite | 极速 HMR，ESM 原生支持 |
| 单元/组件测试 | Vitest + Testing Library | Vite 生态原生，API 兼容 Jest |
| E2E 测试 | Playwright | 多浏览器、自动等待、trace 调试 |
| 代码质量 | ESLint + Prettier + typescript-eslint | 统一风格，自动格式化 |
| Git Hooks | Husky + lint-staged + commitlint | 提交前自动检查，规范 commit message |
| 版本管理 | Changesets | 原生支持 monorepo 多包版本，自动生成 CHANGELOG |
采用 pnpm workspace + Turborepo，推荐目录结构：
my-react-app/
├── pnpm-workspace.yaml # workspace 配置
├── turbo.json # Turborepo 任务管道配置
├── package.json # 根 package.json（scripts + devDeps）
├── .changeset/ # Changesets 配置
├── .husky/ # Git hooks
├── apps/ # 应用层
│ ├── web/ # 主 Web 应用
│ │ ├── src/
│ │ │ ├── app/ # 入口、路由配置、全局 Provider
│ │ │ ├── features/ # 按功能模块组织（核心）
│ │ │ │ └── auth/
│ │ │ │ ├── components/
│ │ │ │ ├── hooks/
│ │ │ │ ├── api/
│ │ │ │ ├── stores/
│ │ │ │ ├── types/
│ │ │ │ └── index.ts
│ │ │ ├── components/ # 应用级通用组件
│ │ │ ├── hooks/ # 应用级通用 hooks
│ │ │ ├── lib/ # 工具函数、API 客户端、Query 配置
│ │ │ └── test/ # 测试工具、setup、mocks
│ │ ├── e2e/ # Playwright E2E 测试
│ │ ├── vite.config.ts
│ │ └── package.json
│ └── docs/ # 文档站（可选）
├── packages/ # 共享包
│ ├── ui/ # 共享 UI 组件库
│ │ ├── src/
│ │ ├── package.json
│ │ └── tsconfig.json
│ ├── utils/ # 共享工具函数
│ ├── tsconfig/ # 共享 TypeScript 配置
│ │ ├── base.json
│ │ ├── react.json
│ │ └── package.json
│ └── eslint-config/ # 共享 ESLint 配置
│ ├── index.js
│ └── package.json
├── docs/ # 项目文档（需求/设计/ADR/指南）
└── tooling/ # 工具配置（可选）
└── prettier-config/
pnpm-workspace.yaml：