技能介绍

它解决什么问题

团队里最常见的前端腐化不是缺框架，而是约定没有被强制执行：有人用 useEffect + fetch + useState 手写数据请求，有人引入 Redux 只为存一个弹窗开关，有人手写 tailwind.config.ts 与 v4 的 CSS-first 配置冲突，最后 pnpm build 和 pnpm test 各跑各的。stack-fe-react 把一套经过验证的技术选型和工程约束固化下来，让生成、重构、评审代码时的判断标准统一。

它如何工作

核心不是文档，而是 assets/frontend-template/ 这个脚手架工程——它已经通过 pnpm install && pnpm build && pnpm test，包含 features/projects 参考模块。技能的工作方式是先定位、再动手：

技术栈基准：TypeScript strict 且禁 any；React 19 仅函数式组件并启用 React Compiler；Vite + @vitejs/plugin-react；包管理只认 pnpm；路由用 React Router v7 默认库模式；服务端状态走 TanStack Query 的 useSuspenseQuery；客户端状态用 Zustand，禁 Redux；请求统一 Axios 实例与拦截器；样式用 Tailwind v4 的 @theme 而非配置文件；组件库用 shadcn/ui；表单用 React Hook Form + Zod。
新建项目：复制模板后改名、改 package.json 与 index.html 标题、调整 src/index.css 的 @theme token、用 npx shadcn@latest add 按需加组件，最后必须让 pnpm build 与 pnpm test 全绿。
代码组织铁律：业务代码一律进 features/<name>/，feature 内自包含 api/、types/、components/，index.html 必须在项目根目录。
数据获取铁律：loading/error 交给 <Suspense> 与 <ErrorBoundary>，组件内不写 if (isLoading) return ...；响应用 z.parse() 解析，类型由 z.infer 推导；写操作用 useMutation，成功后精确失效相关 queryKey。
提交前自检清单：逐条确认没有 useEffect 手写请求、没有禁用库、没有手动 useMemo/useCallback/React.memo、核心逻辑有测试等。

详细的库选型理由、React Compiler 说明和 Router 模式选择见 references/stack-rules.md，代码质量与测试规范见 references/coding-style.md。

适用边界

这套规范只适配 React 19 + Vite + pnpm 的项目。需要 SSR/SEO 时应把 Router 切到框架模式，但模板本身是纯 SPA 起手。它明确禁止 npm/yarn、Redux、lodash/moment、styled-components/emotion、AntD/MUI/Element，历史项目迁移过来要先做技术债盘点。模板默认开 React Compiler，所以不要再手动补 memo 优化；如果构建环境无法用 Babel 管线，可换 -swc 版插件提速。