name	vercel-react-best-practices
description	Vercel 官方 React 和 Next.js 性能优化指南。编写、审查或重构 React/Next.js 代码时使用，确保最佳性能模式。触发词涉及 React 组件、Next.js 页面、数据获取、Bundle 优化或性能改进。
license	MIT
metadata	{"author":"vercel","version":"1.0.0"}

Vercel React 最佳实践

React 和 Next.js 应用综合性能优化指南，由 Vercel 维护。包含 8 大类 65 条规则，按影响程度排序，指导自动化重构和代码生成。

适用场景

参考这些指南的时机：

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

规则分类（按优先级）

优先级	分类	影响程度	前缀标识
1	消除瀑布流	关键	`async-`
2	Bundle 大小优化	关键	`bundle-`
3	服务端性能	高	`server-`
4	客户端数据获取	中高	`client-`
5	重渲染优化	中	`rerender-`
6	渲染性能	中	`rendering-`
7	JavaScript 性能	低中	`js-`
8	高级模式	低	`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 大小优化（关键）

bundle-barrel-imports — 直接导入，避免 barrel 文件
bundle-dynamic-imports — 对重型组件使用 next/dynamic
bundle-defer-third-party — 水合后加载分析/日志库
bundle-conditional — 仅在功能激活时加载模块
bundle-preload — hover/focus 时预加载提升感知速度

3. 服务端性能（高）

server-auth-actions — Server Actions 鉴权同 API 路径
server-cache-react — 用 React.cache() 实现单请求去重
server-cache-lru — 用 LRU cache 实现跨请求缓存
server-dedup-props — 避免 RSC props 重复序列化
server-hoist-static-io — 静态 I/O（字体、logo）提升到模块级
server-serialization — 最小化传递给客户端组件的数据
server-parallel-fetching — 重构组件并行化 fetch
server-parallel-nested-fetching — 用 Promise.all 链式处理嵌套 fetch
server-after-nonblocking — 用 after() 处理非阻塞操作

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

client-swr-dedup — 用 SWR 自动请求去重
client-event-listeners — 全局事件监听器去重
client-passive-event-listeners — 滚动使用 passive 监听器
client-localstorage-schema — localStorage 数据版本化并最小化

5. 重渲染优化（中）

rerender-defer-reads — 仅在回调中使用的状态不要订阅
rerender-memo — 将昂贵计算提取到 memoized 组件
rerender-memo-with-default-value — 提升 non-primitive 默认 props
rerender-dependencies — effect 中使用 primitive dependencies
rerender-derived-state — 订阅派生布尔值，而非原始值
rerender-derived-state-no-effect — 渲染期间派生状态，而非 effect
rerender-functional-setstate — 稳定回调使用函数式 setState
rerender-lazy-state-init — useState 传入函数处理昂贵初始值
rerender-simple-expression-in-memo — 简单 primitive 不用 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-animate-svg-wrapper — 动画 div wrapper，而非 SVG 元素
rendering-content-visibility — 长列表使用 content-visibility
rendering-hoist-jsx — 静态 JSX 提取到组件外
rendering-svg-precision — 降低 SVG 坐标精度
rendering-hydration-no-flicker — 客户端独有数据用内联脚本
rendering-hydration-suppress-warning — 抑制预期的不匹配警告
rendering-activity — show/hide 用 Activity 组件
rendering-conditional-render — 条件渲染用三元，而非 &&
rendering-usetransition-loading — 加载状态优先 useTransition
rendering-resource-hints — 用 React DOM resource hints 预加载
rendering-script-defer-async — script 标签使用 defer 或 async

7. JavaScript 性能（低中）

js-batch-dom-css — 通过 classes 或 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 — 函数尽早 return
js-hoist-regexp — 循环外创建 RegExp
js-min-max-loop — min/max 用循环而非 sort
js-set-map-lookups — O(1) 查找用 Set/Map
js-tosorted-immutable — 不可变性用 toSorted()
js-flatmap-filter — 单次遍历完成 map 和 filter 用 flatMap
js-request-idle-callback — 非关键工作延迟到浏览器空闲

8. 高级模式（低）

advanced-event-handler-refs — 事件处理器存入 refs
advanced-init-once — 应用加载时初始化一次
advanced-use-latest — 稳定回调 refs 用 useLatest

使用方法

查阅单个规则文件获取详细说明和代码示例：

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

每个规则文件包含：

问题原因的简要说明
错误示例代码及解析
正确示例代码及解析
附加背景和参考资料

完整文档

展开所有规则的完整指南见：AGENTS.md

name	vercel-react-best-practices
description	Vercel 官方 React 和 Next.js 性能优化指南。编写、审查或重构 React/Next.js 代码时使用，确保最佳性能模式。触发词涉及 React 组件、Next.js 页面、数据获取、Bundle 优化或性能改进。
license	MIT
metadata	{"author":"vercel","version":"1.0.0"}

Vercel React 最佳实践

React 和 Next.js 应用综合性能优化指南，由 Vercel 维护。包含 8 大类 65 条规则，按影响程度排序，指导自动化重构和代码生成。

适用场景

参考这些指南的时机：

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

规则分类（按优先级）

优先级	分类	影响程度	前缀标识
1	消除瀑布流	关键	`async-`
2	Bundle 大小优化	关键	`bundle-`
3	服务端性能	高	`server-`
4	客户端数据获取	中高	`client-`
5	重渲染优化	中	`rerender-`
6	渲染性能	中	`rendering-`
7	JavaScript 性能	低中	`js-`
8	高级模式	低	`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 大小优化（关键）

bundle-barrel-imports — 直接导入，避免 barrel 文件
bundle-dynamic-imports — 对重型组件使用 next/dynamic
bundle-defer-third-party — 水合后加载分析/日志库
bundle-conditional — 仅在功能激活时加载模块
bundle-preload — hover/focus 时预加载提升感知速度

3. 服务端性能（高）

server-auth-actions — Server Actions 鉴权同 API 路径
server-cache-react — 用 React.cache() 实现单请求去重
server-cache-lru — 用 LRU cache 实现跨请求缓存
server-dedup-props — 避免 RSC props 重复序列化
server-hoist-static-io — 静态 I/O（字体、logo）提升到模块级
server-serialization — 最小化传递给客户端组件的数据
server-parallel-fetching — 重构组件并行化 fetch
server-parallel-nested-fetching — 用 Promise.all 链式处理嵌套 fetch
server-after-nonblocking — 用 after() 处理非阻塞操作

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

client-swr-dedup — 用 SWR 自动请求去重
client-event-listeners — 全局事件监听器去重
client-passive-event-listeners — 滚动使用 passive 监听器
client-localstorage-schema — localStorage 数据版本化并最小化

5. 重渲染优化（中）

rerender-defer-reads — 仅在回调中使用的状态不要订阅
rerender-memo — 将昂贵计算提取到 memoized 组件
rerender-memo-with-default-value — 提升 non-primitive 默认 props
rerender-dependencies — effect 中使用 primitive dependencies
rerender-derived-state — 订阅派生布尔值，而非原始值
rerender-derived-state-no-effect — 渲染期间派生状态，而非 effect
rerender-functional-setstate — 稳定回调使用函数式 setState
rerender-lazy-state-init — useState 传入函数处理昂贵初始值
rerender-simple-expression-in-memo — 简单 primitive 不用 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-animate-svg-wrapper — 动画 div wrapper，而非 SVG 元素
rendering-content-visibility — 长列表使用 content-visibility
rendering-hoist-jsx — 静态 JSX 提取到组件外
rendering-svg-precision — 降低 SVG 坐标精度
rendering-hydration-no-flicker — 客户端独有数据用内联脚本
rendering-hydration-suppress-warning — 抑制预期的不匹配警告
rendering-activity — show/hide 用 Activity 组件
rendering-conditional-render — 条件渲染用三元，而非 &&
rendering-usetransition-loading — 加载状态优先 useTransition
rendering-resource-hints — 用 React DOM resource hints 预加载
rendering-script-defer-async — script 标签使用 defer 或 async

7. JavaScript 性能（低中）

js-batch-dom-css — 通过 classes 或 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 — 函数尽早 return
js-hoist-regexp — 循环外创建 RegExp
js-min-max-loop — min/max 用循环而非 sort
js-set-map-lookups — O(1) 查找用 Set/Map
js-tosorted-immutable — 不可变性用 toSorted()
js-flatmap-filter — 单次遍历完成 map 和 filter 用 flatMap
js-request-idle-callback — 非关键工作延迟到浏览器空闲

8. 高级模式（低）

advanced-event-handler-refs — 事件处理器存入 refs
advanced-init-once — 应用加载时初始化一次
advanced-use-latest — 稳定回调 refs 用 useLatest

使用方法

查阅单个规则文件获取详细说明和代码示例：

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

每个规则文件包含：

问题原因的简要说明
错误示例代码及解析
正确示例代码及解析
附加背景和参考资料

完整文档

展开所有规则的完整指南见：AGENTS.md

vercel-react-best-practices

Vercel React 最佳实践

适用场景

规则分类（按优先级）

快速参考

1. 消除瀑布流（关键）

2. Bundle 大小优化（关键）

3. 服务端性能（高）

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

5. 重渲染优化（中）

6. 渲染性能（中）

7. JavaScript 性能（低中）

8. 高级模式（低）

使用方法

完整文档

同仓库更多 Skills

同仓库更多 Skills

Vercel React 最佳实践

适用场景

规则分类（按优先级）

快速参考

1. 消除瀑布流（关键）

2. Bundle 大小优化（关键）

3. 服务端性能（高）

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

5. 重渲染优化（中）

6. 渲染性能（中）

7. JavaScript 性能（低中）

8. 高级模式（低）

使用方法

完整文档