vercel-react-only-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vercel React Best Practices

Vercel React 最佳实践

Comprehensive performance optimization guide for React applications, maintained by Vercel. Contains 40+ rules across 7 categories, prioritized by impact to guide automated refactoring and code generation.

由Vercel维护的React应用全面性能优化指南，涵盖7个类别下的40+条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing new React components
Implementing client-side data fetching
Reviewing code for performance issues
Refactoring existing React code
Optimizing bundle size or load times

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

编写新的React组件
实现客户端数据获取逻辑
审查代码以排查性能问题
重构现有React代码
优化包体积或加载时间

Rule Categories by Priority

按优先级划分的规则类别


async-
bundle-
client-
rerender-
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	Rendering Performance	MEDIUM	`rendering-`
6	JavaScript Performance	LOW-MEDIUM	`js-`
7	Advanced Patterns	LOW	`advanced-`


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

优先级	类别	影响程度	前缀
1	消除请求瀑布	关键	`async-`
2	包体积优化	关键	`bundle-`
3	客户端数据获取	中高	`client-`
4	重渲染优化	中等	`rerender-`
5	渲染性能	中等	`rendering-`
6	JavaScript性能	低中	`js-`
7	进阶模式	低	`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 better-all for partial dependencies
```
async-suspense-boundaries
```
- Use Suspense to stream content

```
async-defer-await
```
- 将await移至实际需要使用的分支中
```
async-parallel
```
- 对独立操作使用Promise.all()
```
async-dependencies
```
- 对部分依赖使用better-all
```
async-suspense-boundaries
```
- 使用Suspense流式传输内容

2. Bundle Size Optimization (CRITICAL)

2. 包体积优化（关键）

```
bundle-barrel-imports
```
- Import directly, avoid barrel files
```
bundle-conditional
```
- Load modules only when feature is activated
```
bundle-preload
```
- Preload on hover/focus for perceived speed

```
bundle-barrel-imports
```
- 直接导入，避免使用桶文件
```
bundle-conditional
```
- 仅在功能激活时加载模块
```
bundle-preload
```
- 在悬停/聚焦时预加载以提升感知速度

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

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

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

```
client-swr-dedup
```
- 使用SWR实现自动请求去重
```
client-event-listeners
```
- 全局事件监听器去重
```
client-passive-event-listeners
```
- 为滚动事件使用被动监听器
```
client-localstorage-schema
```
- 对localStorage数据进行版本控制并精简

4. Re-render Optimization (MEDIUM)

4. 重渲染优化（中等）

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

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

5. Rendering Performance (MEDIUM)

5. 渲染性能（中等）

```
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-hydration-no-flicker
```
- Use inline script for client-only data
```
rendering-hydration-suppress-warning
```
- Suppress expected mismatches
```
rendering-activity
```
- Use Activity component for show/hide
```
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-hydration-no-flicker
```
- 使用内联脚本传递客户端专属数据
```
rendering-hydration-suppress-warning
```
- 抑制预期的不匹配警告
```
rendering-activity
```
- 使用Activity组件处理显示/隐藏逻辑
```
rendering-conditional-render
```
- 使用三元表达式而非&&进行条件渲染
```
rendering-usetransition-loading
```
- 优先使用useTransition处理加载状态

6. JavaScript Performance (LOW-MEDIUM)

6. JavaScript性能（低中）

```
js-batch-dom-css
```
- Group CSS changes via classes or cssText
```
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
```
- 通过类名或cssText批量修改CSS
```
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
```
- 将正则表达式创建逻辑提升至循环外部
```
js-min-max-loop
```
- 使用循环而非排序来获取最小值/最大值
```
js-set-map-lookups
```
- 使用Set/Map实现O(1)时间复杂度的查找
```
js-tosorted-immutable
```
- 使用toSorted()保证不可变性

7. Advanced Patterns (LOW)

7. 进阶模式（低）

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

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

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/async-parallel.md
rules/bundle-barrel-imports.md

Each rule file contains:

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

阅读单个规则文件以获取详细说明与代码示例：

rules/async-parallel.md
rules/bundle-barrel-imports.md

每个规则文件包含：

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

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有规则详细内容的完整指南，请查阅：

AGENTS.md