stack-fe-react — 前端技术栈规范

以 10 年经验前端架构师的标准生成、重构、解释所有前端代码。所有规范的可执行载体是 assets/frontend-template/：一个经过 pnpm install && pnpm build && pnpm test 验证的脚手架工程，含一个 features/projects 参考模块。写代码前先想清楚对应模板中的哪个位置、哪个文件，与其保持一致。

一、技术栈基准

二、新建项目：使用模板脚手架

新建任何前端项目时，必须从模板初始化，禁止从零手写工程文件：

1. 复制 assets/frontend-template/ 到目标位置并改名
2. pnpm install（lock 文件已锁定验证过的版本组合）
3. 修改 package.json name、index.html title、src/index.css 的 @theme 主题 token
4. 按需添加 shadcn 组件：npx shadcn@latest add <component>（配置已在 components.json）
5. 保留 features/projects 模块作为分层参考实现，编写真实业务后删除
6. 验证：pnpm build 与 pnpm test 必须全绿

模板已含：Vite + React Compiler 配置、Tailwind v4 @theme 入口、TS strict 三件套、Biome、Vitest + jsdom、Axios 统一实例、Zustand 示例 store、ErrorBoundary、shadcn 风格 Button 示例、@/ 路径别名。

三、代码组织铁律

src/
├── components/     # 通用组件（ui/ 为 shadcn 组件）
├── features/       # 按业务模块组织，每模块内含 api/ types/ components/ hooks/
├── lib/            # 工具函数、请求实例
├── stores/         # Zustand stores
├── hooks/          # 全局自定义 hooks
├── types/          # 全局 TS 类型
└── test/           # 测试 setup

• 业务代码一律进 features/<模块>/，禁止散落在 components/ 或页面文件里
• feature 内部自包含：API hooks（api/）、Zod schema（types/）、组件（components/）
• index.html 必须在项目根目录，严禁放 public/

四、数据获取铁律（违反视为严重错误）

• 服务端状态一律 useSuspenseQuery/useQuery + TanStack Query 缓存；严禁 useEffect + useState + fetch 手写请求（最常见反模式）
• loading/error 交给 <Suspense> + <ErrorBoundary> 边界；组件内不写 if (isLoading) return ...
• API 响应用 Zod z.parse() 解析，类型从 schema 推导（z.infer）
• 表单提交用 useMutation，成功后精确失效相关 queryKey

五、UI 与样式铁律

• 样式首选 Tailwind 工具类；复杂动画/全局覆盖可写 .css 文件；严禁 styled-components/emotion
• 主题 token 统一定义在 src/index.css 的 @theme 中，使用方引用 bg-primary、text-text-muted 等语义类
• 类名合并用 cn()（clsx + tailwind-merge）
• shadcn 组件缺失时用 CLI 添加，不手写仿造

六、常见场景速查

七、提交前自检清单

• [ ] 无 useEffect 内手写数据请求？服务端状态都走 TanStack Query？
• [ ] 数据组件被 Suspense + ErrorBoundary 包裹？无散落 isLoading 分支？
• [ ] API 响应经 Zod 解析？无手写 as any 断言？
• [ ] 无 any？strict 编译零错误？
• [ ] 无 Redux/lodash/moment/styled-components 等禁用库？
• [ ] 样式走 Tailwind？主题 token 来自 @theme 而非硬编码色值？
• [ ] 无手动 useMemo/useCallback/React.memo（Compiler 已处理）？
• [ ] 业务代码在 features/ 内自包含？
• [ ] 核心逻辑（utils/hooks/api）有测试？
• [ ] pnpm build 与 pnpm test 全绿？

详细库选型规则、React Compiler 说明、Router 模式选择见 references/stack-rules.md；代码质量、注释、测试规范见 references/coding-style.md。