Back to Details

clean-react

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Clean React: Index And Review Guide

Clean React：索引与审查指南

Use this with 
clean-typescript
. React quality comes from small components, explicit data flow, minimal effects, clear state ownership, ownership-based file organization, and behavior-focused tests.
请结合
clean-typescript
使用本指南。React代码的质量源于小型组件、明确的数据流、最少的副作用、清晰的状态归属、基于归属关系的文件组织以及聚焦行为的测试。

Core Rules (R1-R15)

核心规则（R1-R15）

  • R1: Components should have one reason to change.
  • R2: Prefer composition over boolean prop combinations.
  • R3: Keep JSX shallow enough to scan; extract named components for meaningful sections.
  • R4: Effects synchronize with external systems; do not use them for ordinary data derivation.
  • R5: Derive values during render when possible; do not mirror props or computed values into state.
  • R6: Keep state as local as possible and lift it only when multiple owners need it.
  • R7: Separate server/cache state from local UI state.
  • R8: Custom hooks own reusable stateful behavior, not arbitrary helper code.
  • R9: Event handlers should describe user intent and keep mutation paths obvious.
  • R10: Tests should assert user-visible behavior, accessibility, and state transitions, not incidental styling details.
  • R11: Organize files by dependency ownership; keep private dependencies with their owner and shared dependencies in the nearest 
    common/
    .
  • R12: Model mutually exclusive component modes with discriminated union props.
  • R13: Render explicit loading, error, empty, and success states for remote or nullable data.
  • R14: Keep render pure; side effects belong in event handlers, effects, or boundary code.
  • R15: Prefer realistic test data builders over brittle inline fixtures.
  • R1：组件应该只有一个变更理由。
  • R2：优先使用组合而非布尔属性组合。
  • R3：保持JSX足够简洁以便快速浏览；为有意义的部分提取命名组件。
  • R4：副作用用于与外部系统同步；请勿将其用于普通的数据推导。
  • R5：尽可能在渲染期间推导值；不要将属性或计算值镜像到状态中。
  • R6：尽可能保持状态本地化，仅在多个组件需要时才提升状态。
  • R7：将服务器/缓存状态与本地UI状态分离。
  • R8：自定义hooks负责可复用的有状态行为，而非任意辅助代码。
  • R9：事件处理程序应描述用户意图，并保持变更路径清晰可见。
  • R10：测试应断言用户可见的行为、可访问性和状态转换，而非附带的样式细节。
  • R11：按依赖归属关系组织文件；私有依赖与所属组件放在一起，共享依赖放在最近的
    common/
    目录中。
  • R12：使用可区分联合属性为组件的互斥模式建模。
  • R13：针对远程或可为空的数据，显式渲染加载、错误、空数据和成功状态。
  • R14：保持渲染纯函数；副作用应放在事件处理程序、副作用函数或边界代码中。
  • R15：优先使用真实的测试数据构建器，而非脆弱的内联测试数据。

Skill Routing

技能路由

WorkUse
Component props, JSX, conditional rendering, event handlers
clean-react-components
Effects, dependency arrays, custom hooks
clean-react-hooks
Local state, derived state, reducers, server state
clean-react-state
React Testing Library tests
clean-react-tests
Owner folders, shared dependencies, CSS modules
clean-react-file-organization
Names, comments, functions, general TypeScript
clean-typescript
and focused TypeScript skills
工作内容使用技能
组件属性、JSX、条件渲染、事件处理程序
clean-react-components
副作用、依赖数组、自定义hooks
clean-react-hooks
本地状态、推导状态、reducers、服务器状态
clean-react-state
React Testing Library测试
clean-react-tests
归属文件夹、共享依赖、CSS modules
clean-react-file-organization
命名、注释、函数、通用TypeScript
clean-typescript
及针对性TypeScript技能

Review Checklist

审查清单

  • Components have clear boundaries and one reason to change (R1).
  • Props express one coherent concept and avoid mode explosions (R2).
  • JSX is shallow enough to scan (R3).
  • Effects synchronize with external systems and have correct dependencies (R4).
  • State is not duplicated from props or derived data (R5).
  • State ownership is local where possible and lifted only when needed (R6).
  • Server/cache state is separate from local UI state (R7).
  • Custom hooks expose a small, stable API for reusable stateful behavior (R8).
  • Event handlers describe user intent and keep mutation paths obvious (R9).
  • Tests use accessible queries and real user interactions, without locking in incidental styling details (R10).
  • Files follow dependency ownership, with private dependencies colocated and shared dependencies in nearest 
    common/
    (R11).
  • Mutually exclusive component modes are represented with discriminated union props, not compatible booleans or optional bags (R12).
  • Remote or nullable data has explicit loading, error, empty, and success rendering where those states can occur (R13).
  • Render has no mutations, storage writes, navigation, timers, subscriptions, or other side effects (R14).
  • Tests use realistic builders for repeated props, query data, provider state, or large fixtures (R15).
  • 组件具有清晰的边界且只有一个变更理由（R1）。
  • 属性表达一个连贯的概念，避免模式爆炸（R2）。
  • JSX足够简洁以便快速浏览（R3）。
  • 副作用与外部系统同步且依赖项正确（R4）。
  • 状态未从属性或推导数据中重复（R5）。
  • 状态尽可能本地化，仅在需要时才提升（R6）。
  • 服务器/缓存状态与本地UI状态分离（R7）。
  • 自定义hooks为可复用的有状态行为提供小巧、稳定的API（R8）。
  • 事件处理程序描述用户意图，并保持变更路径清晰可见（R9）。
  • 测试使用可访问的查询和真实用户交互，不依赖附带的样式细节（R10）。
  • 文件遵循依赖归属关系，私有依赖与所属组件共存，共享依赖放在最近的
    common/
    目录中（R11）。
  • 组件的互斥模式通过可区分联合属性表示，而非兼容的布尔值或可选参数包（R12）。
  • 远程或可为空的数据在可能出现的场景下显式渲染加载、错误、空数据和成功状态（R13）。
  • 渲染过程中没有变更、存储写入、导航、计时器、订阅或其他副作用（R14）。
  • 测试对重复属性、查询数据、提供者状态或大型测试数据使用真实的构建器（R15）。

AI Behavior

AI行为规范

When reviewing code, use this skill for the first-pass sweep: identify violations by rule number (e.g., "R4 violation: effect used for derived state").
When writing detailed fixes or explanations for a specific category, read the corresponding sub-skill file before proceeding — for example, read 
../clean-react-components/SKILL.md
when addressing R1/R2/R3/R9/R12/R13/R14 violations. If the Skill tool is available, invoke the skill by name instead. The sub-skills contain code examples and nuance that this index omits.
When fixing or editing code, report what was fixed (e.g., "Fixed: moved derived value out of state (R5)").
审查代码时，使用本技能进行首轮扫描：通过规则编号识别违规情况（例如："R4违规：将副作用用于推导状态"）。
针对特定类别编写详细修复方案或解释时，请先阅读对应的子技能文件再继续——例如，处理R1/R2/R3/R9/R12/R13/R14违规时，阅读
../clean-react-components/SKILL.md
。如果技能工具可用，请直接调用对应技能名称。子技能包含本索引中省略的代码示例和细节。
修复或编辑代码时，请报告修复内容（例如："已修复：将推导值移出状态（R5）"）。