Vercel React最佳实践

适用场景

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

按优先级划分的规则类别

async-

bundle-

server-

client-

rerender-

rendering-

js-

advanced-

快速参考

1. 消除请求瀑布流（关键）

• async-defer-await

  - 将await移至实际使用的分支中

• async-parallel

  - 对独立操作使用Promise.all()

• async-dependencies

  - 对部分依赖使用better-all

• async-api-routes

  - 在API路由中尽早启动promise，延迟await

• async-suspense-boundaries

  - 使用Suspense流式传输内容

2. 包体积优化（关键）

• bundle-barrel-imports

  - 直接导入，避免桶文件

• bundle-dynamic-imports

  - 对大型组件使用next/dynamic

• bundle-defer-third-party

  - 在 hydration 后加载分析/日志工具

• bundle-conditional

  - 仅在功能激活时加载模块

• bundle-preload

  - 在悬停/聚焦时预加载以提升感知速度

3. 服务端性能（高）

• 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-swr-dedup

  - 使用SWR实现自动请求去重

• client-event-listeners

  - 去重全局事件监听器

• client-passive-event-listeners

  - 对滚动操作使用被动监听器

• client-localstorage-schema

  - 对localStorage数据进行版本控制并最小化存储

5. 重渲染优化（中）

• 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-move-effect-to-event

  - 将交互逻辑放入事件处理函数中

• rerender-transitions

  - 使用startTransition处理非紧急更新

• rerender-use-ref-transient-values

  - 使用ref存储频繁变化的临时值

6. 渲染性能（中）

• 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性能（中低）

• 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-event-handler-refs

  - 将事件处理函数存储在refs中

• advanced-init-once

  - 每个应用加载周期仅初始化一次

• advanced-use-latest

  - 使用useLatest获取稳定的回调refs

使用方法

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

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

完整编译文档

AGENTS.md