react-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vercel React Best Practices (Local/Docker)

Vercel React最佳实践（本地/Docker环境）

Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. This version highlights the most important patterns for local installs or dockerized deployments.

由Vercel维护的React与Next.js应用性能优化综合指南。本版本重点介绍了适用于本地安装或容器化（Docker）部署的核心优化模式。

Purpose

目标

Provide a high-signal checklist to avoid async waterfalls, reduce client payloads, and keep UI responsive without relying on hosted or edge-specific optimizations.

提供一份高价值的检查清单，帮助开发者避免async waterfalls、减少客户端负载，并在不依赖托管或边缘专属优化的前提下保持UI响应性。

When to Apply

适用场景

Building or refactoring React components or Next.js pages
Implementing Server Actions, Route Handlers, or data fetching
Reducing startup time or memory footprint for local installs
Debugging sluggish UI or long hydration times
Reviewing code for performance regressions

构建或重构React组件、Next.js页面
实现Server Actions、Route Handlers或数据获取逻辑
缩短本地安装应用的启动时间、降低内存占用
调试UI卡顿或过长的hydration时间
检查代码是否存在性能退化问题

Offline and Docker Focus

离线与Docker环境重点

Optimize for cold-start and steady-state responsiveness over SEO.
Use in-process caches because the server process persists.
Avoid sequential awaits even for local APIs or databases.
Defer non-critical work until after render or after responses are sent.
Minimize RSC props to reduce hydration and memory overhead.

优先优化冷启动与稳态响应性，而非SEO。
使用进程内缓存，因为服务器进程会持续运行。
即使是本地API或数据库操作，也要避免顺序await。
将非关键工作延迟到渲染完成或响应发送后再执行。
尽量减少RSC props，以降低hydration与内存开销。

Top Findings

核心发现

Eliminate async waterfalls by starting work early and awaiting late with
```
Promise.all
```
or
```
better-all
```
.
Use Suspense boundaries to stream UI instead of blocking the whole page on data.
Reduce initial load and memory via dynamic imports, conditional loading, and direct imports.
Minimize RSC payloads; pass only fields used and avoid duplicating serialized data.
Cache hot server work:
```
React.cache
```
per request and LRU for cross-request reuse.
Reduce client work with memoized subtrees, lazy state init, transitions, and
```
content-visibility
```
for large lists.

通过提前启动任务、延迟await（使用
```
Promise.all
```
或
```
better-all
```
）来消除async waterfalls。
使用Suspense边界实现UI流式渲染，而非让整个页面等待数据加载完成。
通过动态导入、条件加载与直接导入减少初始加载时间与内存占用。
最小化RSC负载：仅传递所需字段，避免重复序列化数据。
缓存高频服务器操作：每个请求使用
```
React.cache
```
，跨请求复用使用LRU缓存。
通过记忆化子树、惰性状态初始化、过渡（transitions）以及为长列表设置
```
content-visibility
```
来减少客户端工作负载。

Core Patterns

核心模式

```
async-parallel
```
and
```
async-api-routes
```
to eliminate waterfalls
```
async-suspense-boundaries
```
to stream slow sections

bundle-barrel-imports

and

bundle-dynamic-imports

to reduce startup cost

```
server-serialization
```
and
```
server-dedup-props
```
to shrink RSC payloads
```
server-cache-react
```
and
```
server-cache-lru
```
to reuse hot work

rerender-lazy-state-init

and

rerender-transitions

for responsive UI

```
rendering-content-visibility
```
for long lists
```
client-swr-dedup
```
for fetch deduplication

```
async-parallel
```
与
```
async-api-routes
```
：消除异步瀑布流
```
async-suspense-boundaries
```
：流式渲染慢加载区域

bundle-barrel-imports

与

bundle-dynamic-imports

：降低启动成本

```
server-serialization
```
与
```
server-dedup-props
```
：压缩RSC负载
```
server-cache-react
```
与
```
server-cache-lru
```
：复用高频操作结果

rerender-lazy-state-init

与

rerender-transitions

：提升UI响应性

```
rendering-content-visibility
```
：优化长列表渲染
```
client-swr-dedup
```
：实现请求去重

Outputs

输出产物

```
REACT_PATTERNS.md
```
for a condensed, offline-focused guide
```
AGENT.md
```
for the full compiled reference

```
REACT_PATTERNS.md
```
：精简版离线环境优化指南
```
AGENT.md
```
：完整编译版参考文档

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-`

How to Use

使用方法

Start with

REACT_PATTERNS.md

for the condensed guidance.

首先阅读

REACT_PATTERNS.md

获取精简版指导。

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENT.md

如需查看包含所有扩展规则的完整指南，请参考

AGENT.md