CLAUDE.md@by-framework/react git:20260320.fcf2609A

Immutable. This exact content is served forever at /api/v1/blob/57d787a21faa7dee.

# React 19 + Vite SPA 项目

## 技术栈
- React 19 + TypeScript，Vite 6 构建
- React Router v7 路由管理
- Zustand 状态管理（轻量场景用 Jotai）
- Tailwind CSS 4 样式方案
- Vitest + React Testing Library 测试

## 项目结构
```
src/
  components/    # 可复用 UI 组件（纯展示，无业务逻辑）
  pages/         # 页面级组件，对应路由
  hooks/         # 自定义 hooks
  stores/        # Zustand store 定义
  lib/           # 工具函数、API 客户端
  types/         # TypeScript 类型定义
```

## 开发规范
- 组件使用函数式写法 + TypeScript，Props 用 interface 定义
- 优先使用 React 19 新特性：`use()` hook 处理 Promise/Context，`useOptimistic` 管理乐观更新
- 了解 Server Components 概念，但本项目为纯 SPA，所有组件均为 Client Components
- 使用 `React.lazy()` + `Suspense` 做路由级代码分割
- 状态管理原则：组件本地状态用 `useState`，跨组件共享用 Zustand，服务端状态用 TanStack Query

## 路由
- React Router v7 使用 `createBrowserRouter` + `RouterProvider` 模式
- 数据加载用 `loader`，表单提交用 `action`
- 路由定义集中在 `src/router.tsx`

## 样式
- Tailwind CSS utility class 优先，组件变体用 `clsx` 或 `cva` 管理条件样式

## 测试
- 运行测试：`npx vitest` 或 `npx vitest run`
- 单个文件：`npx vitest src/components/Button.test.tsx`
- 组件测试用 `render` + `screen` + `userEvent`，优先按角色/文本查询 DOM
- 异步断言使用 `waitFor` 或 `findBy*` 查询

## 常用命令
```bash
npm run dev          # 启动开发服务器（默认 5173 端口）
npm run build        # 生产构建，输出到 dist/
npm run preview      # 预览生产构建
npm run lint         # ESLint 检查
npm run test         # 运行测试
```

## 常见陷阱
- `useEffect` 在 StrictMode 下开发时会执行两次，这是预期行为
- Vite 环境变量必须以 `VITE_` 前缀开头才能在客户端访问
- Tailwind v4 使用 CSS-first 配置，不再需要 `tailwind.config.js`
- 路由中使用 `loader` 返回数据时，组件通过 `useLoaderData()` 获取