react-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Best Practices

React最佳实践

Performance optimization guide for client-side React applications. Contains 47 rules across 8 categories, prioritized by impact. Adapted from Vercel Engineering's guidelines, filtered for client-only React + Vite (no Next.js / SSR).

面向客户端React应用的性能优化指南。包含8大类共47条规则，按影响优先级排序。改编自Vercel工程团队指南，筛选适配纯客户端React + Vite场景（不含Next.js / SSR）。

When to Apply

适用场景

Reference these guidelines when:

Writing new React components or hooks
Reviewing code for performance issues
Refactoring existing React code
Optimizing bundle size or render performance
Writing or reviewing
```
useEffect
```
usage

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

编写新的React组件或hooks
评审代码的性能问题
重构现有React代码
优化包体积或渲染性能
编写或评审
```
useEffect
```
用法

Rule Categories by Priority

按优先级划分的规则类别


async-
bundle-
client-
rerender-
useeffect-
rendering-
js-
advanced-

Priority	Category	Impact	Prefix
1	Eliminating Waterfalls	CRITICAL	`async-`
2	Bundle Size Optimization	CRITICAL	`bundle-`
3	Client-Side Data Fetching	MEDIUM-HIGH	`client-`
4	Re-render Optimization	MEDIUM	`rerender-`
5	useEffect Patterns	MEDIUM	`useeffect-`
6	Rendering Performance	MEDIUM	`rendering-`
7	JavaScript Performance	LOW-MEDIUM	`js-`
8	Advanced Patterns	LOW	`advanced-`


async-
bundle-
client-
rerender-
useeffect-
rendering-
js-
advanced-

优先级	类别	影响程度	前缀
1	消除瀑布流	关键	`async-`
2	包体积优化	关键	`bundle-`
3	客户端数据获取	中高	`client-`
4	重渲染优化	中等	`rerender-`
5	useEffect使用模式	中等	`useeffect-`
6	渲染性能	中等	`rendering-`
7	JavaScript性能	中低	`js-`
8	高级模式	低	`advanced-`

Quick Reference

快速参考

1. Eliminating Waterfalls (CRITICAL)

1. 消除瀑布流（关键）

```
async-defer-await
```
— Move await into branches where actually used
```
async-parallel
```
— Use Promise.all() for independent operations
```
async-dependencies
```
— Use promise chaining for partial dependencies
```
async-api-routes
```
— Start promises early, await late

```
async-defer-await
```
— 将await移到实际需要使用的分支中
```
async-parallel
```
— 独立操作使用Promise.all()并行处理
```
async-dependencies
```
— 存在部分依赖时使用Promise链式调用
```
async-api-routes
```
— 尽早启动Promise，延后await

2. Bundle Size Optimization (CRITICAL)

2. 包体积优化（关键）

```
bundle-barrel-imports
```
— Import directly, avoid barrel files
```
bundle-conditional
```
— Load modules only when feature is activated
```
bundle-defer-third-party
```
— Load analytics/logging after mount
```
bundle-preload
```
— Preload on hover/focus for perceived speed

```
bundle-barrel-imports
```
— 直接导入模块，避免桶文件
```
bundle-conditional
```
— 仅在功能启用时加载对应模块
```
bundle-defer-third-party
```
— 挂载后再加载分析/日志类第三方脚本
```
bundle-preload
```
— hover/聚焦时预加载资源以提升感知速度

3. Client-Side Data Fetching (MEDIUM-HIGH)

3. 客户端数据获取（中高）

```
client-event-listeners
```
— Deduplicate global event listeners
```
client-passive-event-listeners
```
— Use passive listeners for scroll/touch
```
client-swr-dedup
```
— Use SWR for automatic request deduplication
```
client-localstorage-schema
```
— Version and minimize localStorage data

```
client-event-listeners
```
— 对全局事件监听器做去重处理
```
client-passive-event-listeners
```
— 滚动/触摸事件使用passive监听器
```
client-swr-dedup
```
— 使用SWR实现请求自动去重
```
client-localstorage-schema
```
— 对localStorage数据做版本管理并精简体积

4. Re-render Optimization (MEDIUM)

4. 重渲染优化（中等）

```
rerender-derived-state-no-effect
```
— Derive state during render, not effects
```
rerender-defer-reads
```
— Don't subscribe to state only used in callbacks
```
rerender-simple-expression-in-memo
```
— Avoid memo for simple primitives
```
rerender-memo-with-default-value
```
— Hoist default non-primitive props
```
rerender-memo
```
— Extract expensive work into memoized components
```
rerender-dependencies
```
— Use primitive dependencies in effects
```
rerender-move-effect-to-event
```
— Put interaction logic in event handlers
```
rerender-derived-state
```
— Subscribe to derived booleans, not raw values
```
rerender-functional-setstate
```
— Use functional setState for stable callbacks
```
rerender-lazy-state-init
```
— Pass function to useState for expensive values
```
rerender-transitions
```
— Use startTransition for non-urgent updates
```
rerender-use-ref-transient-values
```
— Use refs for transient frequent values

```
rerender-derived-state-no-effect
```
— 在渲染阶段派生状态，而非使用effects
```
rerender-defer-reads
```
— 不要订阅仅在回调中使用的状态
```
rerender-simple-expression-in-memo
```
— 简单原始值避免使用memo
```
rerender-memo-with-default-value
```
— 将默认非原始值props提升到组件外
```
rerender-memo
```
— 将耗时逻辑提取到memo化组件中
```
rerender-dependencies
```
— 在effects中使用原始类型依赖项
```
rerender-move-effect-to-event
```
— 将交互逻辑放到事件处理函数中
```
rerender-derived-state
```
— 订阅派生的布尔值，而非原始值
```
rerender-functional-setstate
```
— 使用函数式setState获取稳定回调
```
rerender-lazy-state-init
```
— 给useState传入函数以懒初始化高开销值
```
rerender-transitions
```
— 非紧急更新使用startTransition
```
rerender-use-ref-transient-values
```
— 频繁变化的临时值使用refs存储

5. useEffect Patterns (MEDIUM)

5. useEffect使用模式（中等）

```
useeffect-anti-patterns
```
— Common mistakes: derived state in effects, effect chains, notifying parents
```
useeffect-alternatives
```
— Decision tree and alternatives: derived state, key prop, event handlers, useSyncExternalStore

```
useeffect-anti-patterns
```
— 常见错误：在effects中使用派生状态、effect链、通知父组件
```
useeffect-alternatives
```
— 决策树与替代方案：派生状态、key prop、事件处理函数、useSyncExternalStore

6. Rendering Performance (MEDIUM)

6. 渲染性能（中等）

```
rendering-animate-svg-wrapper
```
— Animate div wrapper, not SVG element
```
rendering-content-visibility
```
— Use content-visibility for long lists
```
rendering-hoist-jsx
```
— Extract static JSX outside components
```
rendering-svg-precision
```
— Reduce SVG coordinate precision
```
rendering-conditional-render
```
— Use ternary, not && for conditionals
```
rendering-usetransition-loading
```
— Prefer useTransition for loading state

```
rendering-animate-svg-wrapper
```
— 动画作用于div容器，而非SVG元素本身
```
rendering-content-visibility
```
— 长列表使用content-visibility
```
rendering-hoist-jsx
```
— 将静态JSX提取到组件外部
```
rendering-svg-precision
```
— 降低SVG坐标精度
```
rendering-conditional-render
```
— 条件渲染使用三元表达式，而非&&
```
rendering-usetransition-loading
```
— 加载状态优先使用useTransition

7. JavaScript Performance (LOW-MEDIUM)

7. JavaScript性能（中低）

```
js-batch-dom-css
```
— Batch DOM reads/writes to avoid layout thrashing
```
js-index-maps
```
— Build Map for repeated lookups
```
js-cache-property-access
```
— Cache object properties in loops
```
js-cache-function-results
```
— Cache function results in module-level Map
```
js-cache-storage
```
— Cache localStorage/sessionStorage reads
```
js-combine-iterations
```
— Combine multiple filter/map into one loop
```
js-length-check-first
```
— Check array length before expensive comparison
```
js-early-exit
```
— Return early from functions
```
js-hoist-regexp
```
— Hoist RegExp creation outside loops
```
js-min-max-loop
```
— Use loop for min/max instead of sort
```
js-set-map-lookups
```
— Use Set/Map for O(1) lookups
```
js-tosorted-immutable
```
— Use toSorted() for immutability

```
js-batch-dom-css
```
— 批量处理DOM读写以避免布局抖动
```
js-index-maps
```
— 构建Map用于重复查找
```
js-cache-property-access
```
— 在循环中缓存对象属性
```
js-cache-function-results
```
— 在模块级Map中缓存函数结果
```
js-cache-storage
```
— 缓存localStorage/sessionStorage读取结果
```
js-combine-iterations
```
— 将多次filter/map合并为一次循环
```
js-length-check-first
```
— 高开销比较前先检查数组长度
```
js-early-exit
```
— 函数尽早返回
```
js-hoist-regexp
```
— 将RegExp创建提升到循环外部
```
js-min-max-loop
```
— 使用循环求最值，而非sort
```
js-set-map-lookups
```
— 使用Set/Map实现O(1)查找
```
js-tosorted-immutable
```
— 使用toSorted()实现不可变性

8. Advanced Patterns (LOW)

8. 高级模式（低）

```
advanced-init-once
```
— Initialize app once per app load
```
advanced-event-handler-refs
```
— Store event handlers in refs
```
advanced-use-latest
```
— useEffectEvent for stable callback refs

```
advanced-init-once
```
— 应用加载时仅初始化一次
```
advanced-event-handler-refs
```
— 将事件处理函数存储在refs中
```
advanced-use-latest
```
— 使用useEffectEvent获取稳定的回调ref

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

references/async-parallel.md
references/rerender-derived-state-no-effect.md
references/useeffect-anti-patterns.md

Each reference file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

查阅各参考文件获取详细说明和代码示例：

references/async-parallel.md
references/rerender-derived-state-no-effect.md
references/useeffect-anti-patterns.md

每个参考文件包含：

规则重要性的简要说明
错误代码示例及解释
正确代码示例及解释
额外背景与参考资料