SuperAPI AI 工具集

vercel-react-best-practices

编程与开发

查看项目

更新于 11-15 04:50

技能介绍

用途

Vercel React Best Practices 是一份面向 React 与 Next.js 应用的综合性能优化指南,由 Vercel Engineering 维护。该技能用于在编写、审查或重构 React/Next.js 代码时提供规则参考,包含 65 条规则,分为 8 个类别,并按影响优先级排序,以指导自动化重构和代码生成。

适用场景

技能文档列出以下适用时机:

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

规则分类与优先级

规则按优先级分为 8 类:

  1. 消除瀑布流(CRITICAL,前缀 async-):如将 await 移入实际使用的分支、对独立操作使用 Promise.all()、在 API 路由中尽早启动 Promise 并延迟 await、使用 Suspense 流式传输内容等。
  2. 包体积优化(CRITICAL,前缀 bundle-):如直接导入避免 barrel 文件、对重型组件使用 next/dynamic、在水合后加载分析/日志、按需加载模块、在悬停/聚焦时预加载等。
  3. 服务端性能(HIGH,前缀 server-):如像 API 路由一样对 server actions 进行认证、使用 React.cache() 做单请求去重、使用 LRU 缓存做跨请求缓存、减少传递给客户端组件的数据、并行化数据获取、使用 after() 执行非阻塞操作等。
  4. 客户端数据获取(MEDIUM-HIGH,前缀 client-):如使用 SWR 自动去重请求、去重全局事件监听器、滚动使用 passive 监听器、对 localStorage 数据做版本化与最小化。
  5. 重渲染优化(MEDIUM,前缀 rerender-):如不订阅仅在回调中使用的状态、将昂贵计算提取为 memo 组件、在 effect 中使用原始类型依赖、订阅派生布尔值而非原始值、在渲染期间派生状态而非 effect、使用函数式 setState、对昂贵初始值使用惰性初始化、对非紧急更新使用 startTransition、将组件定义在组件外部等。
  6. 渲染性能(MEDIUM,前缀 rendering-):如动画化 div 包装器而非 SVG 元素、对长列表使用 content-visibility、将静态 JSX 提升到组件外、降低 SVG 坐标精度、使用内联脚本处理仅客户端数据、抑制预期的不匹配警告、使用 Activity 组件显示/隐藏、条件渲染使用三元而非 &&、优先使用 useTransition 表示加载状态、使用 React DOM 资源提示预加载、script 标签使用 defer 或 async。
  7. JavaScript 性能(LOW-MEDIUM,前缀 js-):如通过类或 cssText 批量修改 CSS、为重复查找构建 Map、在循环中缓存对象属性、在模块级 Map 中缓存函数结果、缓存 localStorage/sessionStorage 读取、合并多个 filter/map 为一次循环、在昂贵比较前检查数组长度、函数提前返回、将 RegExp 创建提升到循环外、用循环求 min/max 而非排序、使用 Set/Map 实现 O(1) 查找、使用 toSorted() 保持不可变性、用 flatMap 一次完成映射与过滤、将非关键工作推迟到浏览器空闲时间。
  8. 高阶模式(LOW,前缀 advanced-):如将事件处理器存储在 ref 中、应用每次加载只初始化一次、使用 useLatest 获得稳定回调 ref。

使用方式

技能文档说明,可阅读各规则文件获取详细说明与代码示例,例如 rules/async-parallel.md、rules/bundle-barrel-imports.md。每个规则文件包含:为何重要的简要说明、带解释的错误代码示例、带解释的正确代码示例,以及额外上下文与参考。完整指南(所有规则展开)见 AGENTS.md。

参考材料说明

技能文档指出,所在目录中的 AGENTS.md 是从 Vercel 引入的长篇上游指南,仅作为本技能的补充参考材料;SKILL.md 是可加载的入口和权威来源,不会覆盖或扩展仓库根目录的 AGENTS.md / AGENT_GUIDE.md。