react-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 and Next.js applications, maintained by Vercel. Contains 64 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

由Vercel维护的React和Next.js应用性能优化综合指南。包含8个分类下的64条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing new React components or Next.js pages
Implementing data fetching (client or server-side)
Reviewing code for performance issues
Refactoring existing React/Next.js code
Optimizing bundle size or load times

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

编写新的React组件或Next.js页面
实现数据获取（客户端或服务端）
评审代码以排查性能问题
重构现有React/Next.js代码
优化包体积或加载时间

Rule Categories by Priority

按优先级划分的规则分类


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

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


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

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

Quick Reference

快速参考

1. Eliminating Waterfalls (CRITICAL)

1. 消除请求瀑布流（CRITICAL）

```
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-api-routes
```
- Start promises early, await late in API routes
```
async-suspense-boundaries
```
- Use Suspense to stream content

```
async-defer-await
```
- 将await移至实际需要使用的分支中
```
async-parallel
```
- 对独立操作使用Promise.all()
```
async-dependencies
```
- 对部分依赖使用better-all
```
async-api-routes
```
- 在API路由中尽早启动Promise，延迟await
```
async-suspense-boundaries
```
- 使用Suspense流式传输内容

2. Bundle Size Optimization (CRITICAL)

2. 包体积优化（CRITICAL）

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

```
bundle-barrel-imports
```
- 直接导入，避免桶文件
```
bundle-dynamic-imports
```
- 对大型组件使用next/dynamic
```
bundle-defer-third-party
```
- 在 hydration 后加载分析/日志工具
```
bundle-conditional
```
- 仅在功能激活时加载模块
```
bundle-preload
```
- 在悬停/聚焦时预加载以提升感知速度

3. Server-Side Performance (HIGH)

3. 服务端性能（HIGH）

```
server-auth-actions
```
- Authenticate server actions like API routes
```
server-cache-react
```
- Use React.cache() for per-request deduplication
```
server-cache-lru
```
- Use LRU cache for cross-request caching
```
server-dedup-props
```
- Avoid duplicate serialization in RSC props
```
server-hoist-static-io
```
- Hoist static I/O (fonts, logos) to module level
```
server-serialization
```
- Minimize data passed to client components
```
server-parallel-fetching
```
- Restructure components to parallelize fetches
```
server-after-nonblocking
```
- Use after() for non-blocking operations

```
server-auth-actions
```
- 像API路由一样验证服务端操作
```
server-cache-react
```
- 使用React.cache()实现请求内去重
```
server-cache-lru
```
- 使用LRU缓存实现跨请求缓存
```
server-dedup-props
```
- 避免在RSC props中重复序列化
```
server-hoist-static-io
```
- 将静态I/O（字体、Logo）提升到模块级别
```
server-serialization
```
- 最小化传递给客户端组件的数据
```
server-parallel-fetching
```
- 重构组件以并行化请求
```
server-after-nonblocking
```
- 使用after()处理非阻塞操作

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

4. 客户端数据获取（MEDIUM-HIGH）

```
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数据添加版本并最小化数据量

5. Re-render Optimization (MEDIUM)

5. 重渲染优化（MEDIUM）

```
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-split-combined-hooks
```
- Split hooks with independent dependencies
```
rerender-move-effect-to-event
```
- Put interaction logic in event handlers
```
rerender-transitions
```
- Use startTransition for non-urgent updates
```
rerender-use-deferred-value
```
- Defer expensive renders to keep input responsive
```
rerender-use-ref-transient-values
```
- Use refs for transient frequent values
```
rerender-no-inline-components
```
- Don't define components inside components

```
rerender-defer-reads
```
- 不要订阅仅在回调中使用的状态
```
rerender-memo
```
- 将耗时操作提取到 memoized 组件中
```
rerender-memo-with-default-value
```
- 将非原始类型的默认props提升到外部
```
rerender-dependencies
```
- 在effect中使用原始类型依赖
```
rerender-derived-state
```
- 订阅派生的布尔值，而非原始值
```
rerender-derived-state-no-effect
```
- 在渲染期间派生状态，而非在effect中
```
rerender-functional-setstate
```
- 使用函数式setState以获得稳定的回调
```
rerender-lazy-state-init
```
- 为useState传入函数以处理耗时的初始值
```
rerender-simple-expression-in-memo
```
- 避免对简单原始类型使用memo
```
rerender-split-combined-hooks
```
- 拆分具有独立依赖的hooks
```
rerender-move-effect-to-event
```
- 将交互逻辑放入事件处理函数中
```
rerender-transitions
```
- 使用startTransition处理非紧急更新
```
rerender-use-deferred-value
```
- 延迟耗时渲染以保持输入响应性
```
rerender-use-ref-transient-values
```
- 使用refs存储频繁变化的临时值
```
rerender-no-inline-components
```
- 不要在组件内部定义组件

6. Rendering Performance (MEDIUM)

6. 渲染性能（MEDIUM）

```
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-resource-hints
```
- Use React DOM resource hints for preloading
```
rendering-script-defer-async
```
- Use defer or async on script tags

```
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处理加载状态
```
rendering-resource-hints
```
- 使用React DOM资源提示进行预加载
```
rendering-script-defer-async
```
- 在script标签上使用defer或async

7. JavaScript Performance (LOW-MEDIUM)

7. JavaScript性能（LOW-MEDIUM）

```
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-flatmap-filter
```
- Use flatMap to map and filter in one pass

```
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
```
- 将RegExp创建提升到循环外部
```
js-min-max-loop
```
- 使用循环而非排序来获取最小值/最大值
```
js-set-map-lookups
```
- 使用Set/Map实现O(1)查找
```
js-tosorted-immutable
```
- 使用toSorted()实现不可变性
```
js-flatmap-filter
```
- 使用flatMap在一次遍历中完成映射和过滤

8. Advanced Patterns (LOW)

8. 高级模式（LOW）

```
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
```
- 将事件处理函数存储在refs中
```
advanced-init-once
```
- 每次应用加载仅初始化一次
```
advanced-use-latest
```
- 使用useLatest获取稳定的回调refs

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