用途
React Conventions 是一个 React 框架技能,为现代 React 提供具体规则:函数组件、Hooks、Server Components、Actions 以及 React Compiler。它把 core-typescript 和 architecture-and-design 中以通用方式设定的规则,转化为 React 形式。
该技能建立在 core-typescript(语言规则)和 architecture-and-design(设计)之上。仅当任务涉及对应层时才加载同级技能;若未加载,则用通用知识应用该层,不要阻塞。
SKILL.md 是自足的:下方 Ruleset 是完整、可执行的清单。每个 references/<topic>.md 保存该组的推理与 ❌ / ✅ 代码,references/worked-example.md 提供一次完整审查过程;在运行时允许时打开它们以获取深度。
主要能力
技能提供三种模式,按顺序执行步骤:
生成 — 编写新组件或 Hook
- 保持渲染纯净;为 props 标注类型(purity)。
- 在写 useEffect 之前,先检查 effects —— 大多数并不需要。
- 在渲染期间派生状态;用 key 重置(state)。
- 将 Ruleset 作为检查清单运行。交付前修复每个失败项。
审查 — 检查 pull request 或 diff
- 对 diff 运行 Ruleset。
- 每个失败项写一条发现,使用下方输出格式。
- 排序发现:must-fix 在前,然后 consider。
- 若无失败,用一行说明。不要编造发现。
迁移 — 现代化旧版 React
- 运行 React 19 类型 codemod,然后运行 forwardRef 和 <Context.Provider> codemod。
- 开启 eslint-plugin-react-hooks(v6 或更高,推荐)并修复每个警告。
- 采用 React Compiler;然后删除仅用于保护引用标识的手写 useMemo / useCallback。
- 每次提交只做一类改动。保持测试通过。
使用方式
输出格式:每行一条发现:
<severity> · <topic> · <file>:<line> — <what is wrong>. <the fix as an action>.
<severity>为 must-fix(违反本技能规则或 lint 规则)或 consider(安全,但规则偏好另一种形式)。<topic>为 Ruleset 主题 slug(effects、state、data-fetching 等)。
每种模式的规则:
- 执行规则时指明 Ruleset 主题。
- 优先使用当前 API 而非其前身:ref 作为 prop 而非 forwardRef,<Context> 而非 <Context.Provider>,Action 而非手动提交 useEffect。
- 在求助于 useEffect 之前,先问代码为何运行。如果答案不是"因为组件在屏幕上且必须与外部系统同步",它就不属于 Effect。
Ruleset 主题概览
- purity:渲染纯净,无 props/state 变更,无渲染体副作用,应用树包裹在 <StrictMode> 中;相同 props、state、context 产生相同 JSX;props 用 type 或 interface 而非 React.FC;ref 作为普通 prop 接受;每文件一个组件;useId() 用于 label/aria-* id;开启 eslint-plugin-react 和 eslint-plugin-react-hooks。
- hooks:每个 Hook 在组件或另一个 Hook 顶层调用,早返回之前;仅从函数组件或自定义 Hook 调用;共享有状态逻辑为 useX 自定义 Hook;依赖数组完整且不被抑制。
- state:状态与使用它的组件同处;可派生值在渲染期间计算;不将 prop 镜像到 state;不原地变更 state;依赖前值时用更新器形式;昂贵初始值用惰性形式;多字段一起变化时用 useReducer;外部 store 用 useSyncExternalStore。
- effects:不为渲染数据转换、昂贵计算、prop 变化重置状态、用户事件、POST、状态更新链、通知父组件或一次性应用初始化而使用 Effect;Effect 仅用于与外部系统同步;每个 Effect 有清理;获取数据的 Effect 防止过期响应;可复用 Effect 提取为自定义 Hook;用 Effect Event(useEffectEvent)读取最新值。
- refs:useRef 仅用于必须跨渲染存活且不触发渲染的值;渲染期间不读写 ref.current;ref 为普通 prop;命令式 API 用 useImperativeHandle;ref 回调返回清理函数;导航后、异步操作后、对话框打开时移动焦点;ref 是逃生舱,先尝试 state 或 prop。
- context:Context 仅保存低频、广泛读取的数据;快速变化的值放在自己的 context 或本地 state/带选择器的 store;provider 用 <Context value={…}>(React 19);用 useContext 读取,use(Context) 仅在读取必须条件化时;context 值被 memo 化。
- data-fetching:不用裸 useEffect fetch;每个请求有稳定缓存键;异步读取包裹在 <Suspense> 中并有真实 fallback 和错误边界;渲染错误由类边界或 react-error-boundary 捕获;非紧急更新用 useTransition / useDeferredValue;mutation 从响应更新缓存;useOptimistic 仅在有回滚路径时。
- forms:提交由 useActionState 驱动的 <form action={submitAction}>;子级 pending 状态通过 useFormStatus;乐观行用 useOptimistic;输入不在受控与非受控之间中途切换;验证器基于服务端同一 schema 构建,服务端重新验证;失败提交后保留输入值。
- server-client:组件默认为 Server Components;需要数据的 Server Component 是 async 并在渲染中 await;'use client' 放在最小交互叶节点;服务端函数标记 'use server' 并作为 Action 调用;跨边界 props 可序列化;服务端专用模块不可从 'use client' 文件访问;数据获取在 Server Component 或 loader 中进行。
- rendering:React Compiler 开启;未开启时 memo/useMemo/useCallback 仅出现在用 Profiler 测量过的路径;渲染中不构建新对象/数组/函数传给 memo 化子组件;key 为稳定 id;路由用 lazy() + <Suspense> 代码分割;超过几百行的列表虚拟化;<title>/<meta>/<link rel> 在拥有它们的组件中渲染;modal/tooltip/toast 通过 createPortal 渲染。
- testing:用 React Testing Library 渲染;按 role 和可访问名称查询;交互由 @testing-library/user-event 驱动;不 mock 模块或 Hook 代替数据;断言针对渲染输出;自定义 Hook 通过使用它的组件测试;createPortal 内容通过 screen 查询;不用 shallow rendering、Enzyme 或宽泛快照。
适用场景
- 编写新的 React 函数组件或自定义 Hook。
- 审查 React 相关的 pull request 或 diff。
- 将旧版 React 代码迁移到现代 API(React 19 类型、ref 作为 prop、<Context>、React Compiler)。
- 需要一套可执行的 React 规则清单来保证代码质量。
限制
本技能是 React 框架规则,不覆盖:
- 语言规则(见 core-typescript)或框架无关架构(见 architecture-and-design)。
- 特定框架的路由、loader 或元数据 API(Next.js、React Router、TanStack Start)—— 此处的 RSC 和数据获取规则适用,框架自身约定不适用。
- Store 库(Redux Toolkit、Zustand、Jotai)—— 使用 architecture-and-design 中的状态层级,仅在其要求时使用 store。
- 无障碍深度 —— useId 和焦点管理在合适处提及;完整视角在 accessibility。
- React Native 和动画库。样式属于 styling-and-design-tokens;i18n(react-intl 策略)属于 i18n-and-localization;加载和交互成本属于 web-performance。
- 其他框架 —— angular 和 vue 是同级技能;此处每条规则都是 React 特有的。
React Compiler 已稳定(1.0)。此处规则假设你采用它;若未采用,则渲染规则中关于手动 memo 化的部分适用。
引用
本技能与以下技能组合:
- core-typescript —— 语言基础;JSX 和 Hooks 不豁免代码遵守它。
- architecture-and-design —— 设计层。冲突时它决定设计,本技能决定 React API。
- accessibility —— UI 审查视角;React 的工具是 useId、基于 ref 的焦点和原语库(Radix、React Aria)。
- test-quality —— 评判本技能 testing 组产生的单个测试。
- angular / vue —— 同级框架技能。