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 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

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

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-

优先级	类别	影响程度	前缀
1	消除请求瀑布流	关键	`async-`
2	包体积优化	关键	`bundle-`
3	服务端性能	高	`server-`
4	客户端数据获取	中高	`client-`
5	重渲染优化	中	`rerender-`
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 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. 包体积优化（关键）

```
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
```
- 在 hover/focus 时预加载以提升感知速度

3. Server-Side Performance (HIGH)

3. 服务端性能（高）

```
server-cache-react
```
- Use React.cache() for per-request deduplication
```
server-cache-lru
```
- Use LRU cache for cross-request caching
```
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-cache-react
```
- 使用React.cache()实现请求内去重
```
server-cache-lru
```
- 使用LRU缓存实现跨请求缓存
```
server-serialization
```
- 减少传递给客户端组件的数据量
```
server-parallel-fetching
```
- 重构组件以并行化数据获取
```
server-after-nonblocking
```
- 对非阻塞操作使用after()

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

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

```
client-swr-dedup
```
- Use SWR for automatic request deduplication
```
client-event-listeners
```
- Deduplicate global event listeners

```
client-swr-dedup
```
- 使用SWR实现自动请求去重
```
client-event-listeners
```
- 对全局事件监听器进行去重

5. Re-render Optimization (MEDIUM)

5. 重渲染优化（中）

```
rerender-defer-reads
```
- Don't subscribe to state only used in callbacks
```
rerender-memo
```
- Extract expensive work into memoized components
```
rerender-dependencies
```
- Use primitive dependencies in effects
```
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-defer-reads
```
- 不要订阅仅在回调中使用的状态
```
rerender-memo
```
- 将昂贵的操作提取到 memoized 组件中
```
rerender-dependencies
```
- 在effects中使用原始类型依赖
```
rerender-derived-state
```
- 订阅派生的布尔值，而非原始值
```
rerender-functional-setstate
```
- 使用函数式setState以获取稳定回调
```
rerender-lazy-state-init
```
- 对昂贵的值，向useState传递函数
```
rerender-transitions
```
- 使用startTransition处理非紧急更新

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-hydration-no-flicker
```
- Use inline script for client-only data
```
rendering-activity
```
- Use Activity component for show/hide
```
rendering-conditional-render
```
- Use ternary, not && for conditionals

```
rendering-animate-svg-wrapper
```
- 为div包装器添加动画，而非SVG元素
```
rendering-content-visibility
```
- 对长列表使用content-visibility
```
rendering-hoist-jsx
```
- 将静态JSX提取到组件外部
```
rendering-svg-precision
```
- 降低SVG坐标精度
```
rendering-hydration-no-flicker
```
- 使用内联脚本处理仅客户端数据
```
rendering-activity
```
- 使用Activity组件实现显示/隐藏
```
rendering-conditional-render
```
- 使用三元表达式而非&&进行条件渲染

7. JavaScript Performance (LOW-MEDIUM)

7. 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
```
- 将RegExp创建提升到循环外部
```
js-min-max-loop
```
- 使用循环而非排序来获取min/max
```
js-set-map-lookups
```
- 使用Set/Map实现O(1)查找
```
js-tosorted-immutable
```
- 使用toSorted()实现不可变性

8. Advanced Patterns (LOW)

8. 高级模式（低）

```
advanced-event-handler-refs
```
- Store event handlers in refs
```
advanced-use-latest
```
- useLatest for stable callback refs

```
advanced-event-handler-refs
```
- 将事件处理程序存储在refs中
```
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
rules/_sections.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
rules/_sections.md

每个规则文件包含：

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

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有展开规则的完整指南，请查看：

AGENTS.md

When to Use

适用场景

This skill is applicable to execute the workflow or actions described in the overview.

本指南适用于执行概述中描述的工作流或操作。