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

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

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
```
- 在鼠标悬停/聚焦时预加载资源以提升感知速度

3. Server-Side Performance (HIGH)

3. 服务端性能（高）

```
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-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-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-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. 重渲染优化（中）

```
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
```
- 将昂贵的逻辑提取到 memoized 组件中
```
rerender-memo-with-default-value
```
- 将非原始类型的默认属性提升到外部
```
rerender-dependencies
```
- 在 effects 中使用原始类型依赖
```
rerender-derived-state
```
- 订阅派生的布尔值而非原始值
```
rerender-derived-state-no-effect
```
- 在渲染期间派生状态，而非在 effects 中
```
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
```
- 使用 refs 存储频繁变化的临时值

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-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 处理加载状态

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
```
- 使用循环而非排序来获取最小值/最大值
```
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-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