react-code-smells

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Principal Engineering React Best Practices

高级工程师级React最佳实践

Principal-engineer-level refactoring guide for React applications. Contains 42 rules across 8 categories, prioritized by impact from critical (state architecture, composition) to incremental (testability). Each rule includes code smell indicators, before/after examples, and safe transformation steps.

面向React应用的高级工程师级重构指南。包含8个分类下的42条规则，按影响优先级排序，从关键（状态架构、组件组合）到增量（可测试性）。每条规则都包含代码异味指标、重构前后示例以及安全的转换步骤。

When to Apply

适用场景

Reference these guidelines when:

Refactoring existing React codebases
Reviewing PRs for architectural issues
Identifying technical debt
Planning large-scale refactoring efforts
Deciding whether to extract, inline, or restructure components
Improving testability of React code

在以下场景中参考本指南：

重构现有React代码库
审查PR中的架构问题
识别技术债务
规划大规模重构工作
决定是否提取、内联或重组组件
提升React代码的可测试性

Rule Categories by Priority

按优先级划分的规则分类


state-
comp-
abs-
couple-
hook-
render-
effect-
test-

Priority	Category	Impact	Prefix
1	State Architecture	CRITICAL	`state-`
2	Component Composition	CRITICAL	`comp-`
3	Abstraction Quality	HIGH	`abs-`
4	Coupling & Cohesion	HIGH	`couple-`
5	Hook Hygiene	MEDIUM-HIGH	`hook-`
6	Render Patterns	MEDIUM	`render-`
7	Side Effect Management	MEDIUM	`effect-`
8	Testability	LOW-MEDIUM	`test-`


state-
comp-
abs-
couple-
hook-
render-
effect-
test-

优先级	分类	影响级别	前缀
1	状态架构	关键	`state-`
2	组件组合	关键	`comp-`
3	抽象质量	高	`abs-`
4	耦合与内聚	高	`couple-`
5	Hook规范	中高	`hook-`
6	渲染模式	中	`render-`
7	副作用管理	中	`effect-`
8	可测试性	中低	`test-`

Quick Reference

快速参考

1. State Architecture (CRITICAL)

1. 状态架构（关键）

```
state-prop-drilling-compound
```
- Replace prop drilling with compound components
```
state-prop-drilling-composition
```
- Replace prop drilling with component composition
```
state-derived-calculation
```
- Replace synchronized state with derived calculations
```
state-machine-complex
```
- Replace boolean explosion with state machines
```
state-colocation
```
- Colocate state with components that use it
```
state-reducer-consolidation
```
- Consolidate related useState calls into useReducer
```
state-context-selector
```
- Use context selectors to prevent cascade re-renders
```
state-url-sync
```
- Move shareable state to URL parameters

```
state-prop-drilling-compound
```
- 用复合组件替代属性透传
```
state-prop-drilling-composition
```
- 用组件组合替代属性透传
```
state-derived-calculation
```
- 用派生计算替代同步状态
```
state-machine-complex
```
- 用状态机替代布尔值膨胀
```
state-colocation
```
- 将状态与使用它的组件放在一起
```
state-reducer-consolidation
```
- 将相关的useState调用合并为useReducer
```
state-context-selector
```
- 使用Context选择器防止级联重渲染
```
state-url-sync
```
- 将可共享状态移至URL参数

2. Component Composition (CRITICAL)

2. 组件组合（关键）

```
comp-render-props-extraction
```
- Extract shared logic with render props or hooks
```
comp-slots-over-props
```
- Use slots/children instead of configuration props
```
comp-god-component-split
```
- Split god components by responsibility
```
comp-controlled-uncontrolled
```
- Choose controlled vs uncontrolled deliberately
```
comp-headless-extraction
```
- Extract headless components for reusable behavior
```
comp-props-spreading
```
- Avoid untyped props spreading
```
comp-polymorphic-as
```
- Use polymorphic 'as' prop for flexible elements
```
comp-children-validation
```
- Validate compound component children

```
comp-render-props-extraction
```
- 用渲染属性或Hooks提取共享逻辑
```
comp-slots-over-props
```
- 使用插槽/子组件替代配置属性
```
comp-god-component-split
```
- 按职责拆分巨型组件
```
comp-controlled-uncontrolled
```
- 谨慎选择受控与非受控组件
```
comp-headless-extraction
```
- 提取无头组件以实现可复用行为
```
comp-props-spreading
```
- 避免无类型的属性展开
```
comp-polymorphic-as
```
- 使用多态
```
as
```
属性实现灵活元素
```
comp-children-validation
```
- 验证复合组件的子组件

3. Abstraction Quality (HIGH)

3. 抽象质量（高）

```
abs-premature-abstraction
```
- Resist premature abstraction (Rule of Three)
```
abs-over-configuration
```
- Prefer composition over configuration
```
abs-extract-custom-hook
```
- Extract custom hooks for reusable logic
```
abs-inline-vs-extract
```
- Know when to inline vs extract components
```
abs-wrong-abstraction-fix
```
- Fix wrong abstractions by inlining first
```
abs-utility-vs-domain
```
- Separate utility hooks from domain hooks

```
abs-premature-abstraction
```
- 避免过早抽象（三次原则）
```
abs-over-configuration
```
- 优先选择组合而非配置
```
abs-extract-custom-hook
```
- 提取自定义Hook以实现可复用逻辑
```
abs-inline-vs-extract
```
- 了解何时内联或提取组件
```
abs-wrong-abstraction-fix
```
- 先通过内联修复错误的抽象
```
abs-utility-vs-domain
```
- 区分工具Hook与领域Hook

4. Coupling & Cohesion (HIGH)

4. 耦合与内聚（高）

```
couple-colocation-files
```
- Colocate related files by feature
```
couple-dependency-injection
```
- Use dependency injection for external services
```
couple-interface-segregation
```
- Apply interface segregation to props
```
couple-circular-deps
```
- Break circular dependencies with inversion
```
couple-stable-imports
```
- Import from stable public APIs only

```
couple-colocation-files
```
- 按功能将相关文件放在一起
```
couple-dependency-injection
```
- 对外部服务使用依赖注入
```
couple-interface-segregation
```
- 对属性应用接口隔离原则
```
couple-circular-deps
```
- 通过反转打破循环依赖
```
couple-stable-imports
```
- 仅从稳定的公共API导入

5. Hook Hygiene (MEDIUM-HIGH)

5. Hook规范（中高）

```
hook-dependency-stability
```
- Ensure hook dependencies are stable
```
hook-composition-over-size
```
- Compose small hooks rather than one large hook
```
hook-return-object-vs-tuple
```
- Choose hook return type by use case
```
hook-conditional-usage
```
- Never call hooks conditionally
```
hook-naming-conventions
```
- Follow hook naming conventions

```
hook-dependency-stability
```
- 确保Hook依赖稳定
```
hook-composition-over-size
```
- 组合小型Hook而非单个大型Hook
```
hook-return-object-vs-tuple
```
- 根据用例选择Hook返回类型
```
hook-conditional-usage
```
- 绝不要有条件地调用Hook
```
hook-naming-conventions
```
- 遵循Hook命名规范

6. Render Patterns (MEDIUM)

6. 渲染模式（中）

```
render-conditional-early-return
```
- Use early returns for conditional rendering
```
render-list-key-stability
```
- Use stable, unique keys for lists
```
render-avoid-inline-objects
```
- Avoid inline objects in JSX props
```
render-fragment-cleanup
```
- Use fragments to avoid wrapper divs

```
render-conditional-early-return
```
- 使用提前返回处理条件渲染
```
render-list-key-stability
```
- 对列表使用稳定且唯一的Key
```
render-avoid-inline-objects
```
- 避免在JSX属性中使用内联对象
```
render-fragment-cleanup
```
- 使用Fragment避免额外的包裹Div

7. Side Effect Management (MEDIUM)

7. 副作用管理（中）

```
effect-to-event-handler
```
- Move event responses from effects to handlers
```
effect-cleanup-required
```
- Always clean up effect side effects
```
effect-single-responsibility
```
- Separate unrelated effects
```
effect-avoid-unnecessary
```
- Remove effects that aren't synchronization

```
effect-to-event-handler
```
- 将事件响应从Effect移至事件处理器
```
effect-cleanup-required
```
- 始终清理Effect的副作用
```
effect-single-responsibility
```
- 分离不相关的Effect
```
effect-avoid-unnecessary
```
- 移除非同步用途的Effect

8. Testability (LOW-MEDIUM)

8. 可测试性（中低）

```
test-seam-creation
```
- Create seams for testable components
```
test-behavior-over-implementation
```
- Test behavior, not implementation details
```
test-extract-for-testability
```
- Extract logic to hooks for testability
```
test-mock-boundaries
```
- Mock at boundaries, not internal details

```
test-seam-creation
```
- 为可测试组件创建接缝
```
test-behavior-over-implementation
```
- 测试行为而非实现细节
```
test-extract-for-testability
```
- 将逻辑提取到Hook以提升可测试性
```
test-mock-boundaries
```
- 在边界处Mock而非内部细节

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明和代码示例：

章节定义 - 分类结构和影响级别
规则模板 - 添加新规则的模板

Related Skills

References

参考资料

react.dev - Official React documentation
kentcdodds.com - Advanced React patterns
patterns.dev - Design patterns in JavaScript
testing-library.com - Testing best practices

react.dev - React官方文档
kentcdodds.com - 高级React模式
patterns.dev - JavaScript设计模式
testing-library.com - 测试最佳实践