--- name: vercel-react-best-practices-cn description: | 来自 Vercel 工程团队的 React 和 Next.js 性能优化指南。在编写、审查或重构 React/Next.js 代码时使用此 Skill 以确保最佳性能模式。触发于涉及 React 组件、Next.js 页面、数据获取、包优化或性能改进的任务。 license: MIT metadata: author: vercel version: "1.0.0" language: zh-CN --- # Vercel React 最佳实践 React 和 Next.js 应用的全面性能优化指南，由 Vercel 维护。包含 8 个类别的 64 条规则，按影响优先级排序，指导自动化重构和代码生成。 ## 应用时机在以下情况下参考这些指南： - 编写新的 React 组件或 Next.js 页面 - 实现数据获取（客户端或服务端） - 审查代码性能问题 - 重构现有 React/Next.js 代码 - 优化包大小或加载时间 ## 按优先级分类的规则类别 | 优先级 | 类别 | 影响 | 前缀 | |--------|------|------|------| | 1 | 消除瀑布流 | 关键 | `async-` | | 2 | 包大小优化 | 关键 | `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-barrel-imports` - 直接导入，避免桶文件 - `bundle-dynamic-imports` - 对重组件使用 next/dynamic - `bundle-defer-third-party` - 水合后加载分析/日志 - `bundle-conditional` - 仅在功能激活时加载模块 - `bundle-preload` - 悬停/聚焦时预加载以提升感知速度 ### 3. 服务端性能（高） - `server-auth-actions` - 像 API 路由一样认证服务器操作 - `server-cache-react` - 使用 React.cache() 进行请求级去重 - `server-cache-lru` - 使用 LRU 缓存进行跨请求缓存 - `server-dedup-props` - 避免在 RSC props 中重复序列化 - `server-hoist-static-io` - 将静态 I/O（字体、logo）提升到模块级别 - `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` - 将昂贵工作提取到记忆化组件中 - `rerender-memo-with-default-value` - 提升默认非原始 props - `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-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 包装器，而非 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 处理加载状态 - `rendering-resource-hints` - 使用 React DOM 资源提示预加载 - `rendering-script-defer-async` - 在 script 标签上使用 defer 或 async ### 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 而非 sort - `js-set-map-lookups` - 使用 Set/Map 进行 O(1) 查找 - `js-tosorted-immutable` - 使用 toSorted() 保持不可变 - `js-flatmap-filter` - 使用 flatMap 在一次遍历中映射和过滤 ### 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` --- **中文翻译版** | 原版：vercel-react-best-practices FILE:AGENTS.md # React Best Practices **Version 1.0.0** Vercel Engineering January 2026 > **Note:** > This document is mainly for agents and LLMs to follow when maintaining, > generating, or refactoring React and Next.js codebases. Humans > may also find it useful, but guidance here is optimized for automation > and consistency by AI-assisted workflows. --- ## Abstract Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation. --- ## Table of Contents 1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL** - 1.1 [Defer Await Until Needed](#11-defer-await-until-needed) - 1.2 [Dependency-Based Parallelization](#12-dependency-based-parallelization) - 1.3 [Prevent Waterfall Chains in API Routes](#13-prevent-waterfall-chains-in-api-routes) - 1.4 [Promise.all() for Independent Operations](#14-promiseall-for-independent-operations) - 1.5 [Strategic Suspense Boundaries](#15-strategic-suspense-boundaries) 2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL** - 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports) - 2.2 [Conditional Module Loading](#22-conditional-module-loading) - 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries) - 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components) - 2.5 [Preload Based on User Intent](#25-preload-based-on-user-intent) 3. [Server-Side Performance](#3-server-side-performance) — **HIGH** - 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes) - 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props) - 3.3 [Cross-Request LRU Caching](#33-cross-request-lru-caching) - 3.4 [Hoist Static I/O to Module Level](#34-hoist-static-io-to-module-level) - 3.5 [Minimize Serialization at RSC Boundaries](#35-minimize-serialization-at-rsc-boundaries) - 3.6 [Parallel Data Fetching with Component Composition](#36-parallel-data-fetching-with-component-composition) - 3.7 [Per-Request Deduplication with React.cache()](#37-per-request-deduplication-with-reactcache) - 3.8 [Use after() for Non-Blocking Operations](#38-use-after-for-non-blocking-operations) 4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH** - 4.1 [Deduplicate Global Event Listeners](#41-deduplicate-global-event-listeners) - 4.2 [Use Passive Event Listeners for Scrolling Performance](#42-use-passive-event-listeners-for-scrolling-performance) - 4.3 [Use SWR for Automatic Deduplication](#43-use-swr-for-automatic-deduplication) - 4.4 [Version and Minimize localStorage Data](#44-version-and-minimize-localstorage-data) 5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM** - 5.1 [Calculate Derived State During Rendering](#51-calculate-derived-state-during-rendering) - 5.2 [Defer State Reads to Usage Point](#52-defer-state-reads-to-usage-point) - 5.3 [Do not wrap a simple expression with a primitive result type in useMemo](#53-do-not-wrap-a-simple-expression-with-a-primitive-result-type-in-usememo) - 5.4 [Don't Define Components Inside Components](#54-dont-define-components-inside-components) - 5.5 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#55-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant) - 5.6 [Extract to Memoized Components](#56-extract-to-memoized-components) - 5.7 [Narrow Effect Dependencies](#57-narrow-effect-dependencies) - 5.8 [Put Interaction Logic in Event Handlers](#58-put-interaction-logic-in-event-handlers) - 5.9 [Split Combined Hook Computations](#59-split-combined-hook-computations) - 5.10 [Subscribe to Derived State](#510-subscribe-to-derived-state) - 5.11 [Use Functional setState Updates](#511-use-functional-setstate-updates) - 5.12 [Use Lazy State Initialization](#512-use-lazy-state-initialization) - 5.13 [Use Transitions for Non-Urgent Updates](#513-use-transitions-for-non-urgent-updates) - 5.14 [Use useDeferredValue for Expensive Derived Renders](#514-use-usedeferredvalue-for-expensive-derived-renders) - 5.15 [Use useRef for Transient Values](#515-use-useref-for-transient-values) 6. [Rendering Performance](#6-rendering-performance) — **MEDIUM** - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61-animate-svg-wrapper-instead-of-svg-element) - 6.2 [CSS content-visibility for Long Lists](#62-css-content-visibility-for-long-lists) - 6.3 [Hoist Static JSX Elements](#63-hoist-static-jsx-elements) - 6.4 [Optimize SVG Precision](#64-optimize-svg-precision) - 6.5 [Prevent Hydration Mismatch Without Flickering](#65-prevent-hydration-mismatch-without-flickering) - 6.6 [Suppress Expected Hydration Mismatches](#66-suppress-expected-hydration-mismatches) - 6.7 [Use Activity Component for Show/Hide](#67-use-activity-component-for-showhide) - 6.8 [Use defer or async on Script Tags](#68-use-defer-or-async-on-script-tags) - 6.9 [Use Explicit Conditional Rendering](#69-use-explicit-conditional-rendering) - 6.10 [Use React DOM Resource Hints](#610-use-react-dom-resource-hints) - 6.11 [Use useTransition Over Manual Loading States](#611-use-usetransition-over-manual-loading-states) 7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM** - 7.1 [Avoid Layout Thrashing](#71-avoid-layout-thrashing) - 7.2 [Build Index Maps for Repeated Lookups](#72-build-index-maps-for-repeated-lookups) - 7.3 [Cache Property Access in Loops](#73-cache-property-access-in-loops) - 7.4 [Cache Repeated Function Calls](#74-cache-repeated-function-calls) - 7.5 [Cache Storage API Calls](#75-cache-storage-api-calls) - 7.6 [Combine Multiple Array Iterations](#76-combine-multiple-array-iterations) - 7.7 [Early Length Check for Array Comparisons](#77-early-length-check-for-array-comparisons) - 7.8 [Early Return from Functions](#78-early-return-from-functions) - 7.9 [Hoist RegExp Creation](#79-hoist-regexp-creation) - 7.10 [Use flatMap to Map and Filter in One Pass](#710-use-flatmap-to-map-and-filter-in-one-pass) - 7.11 [Use Loop for Min/Max Instead of Sort](#711-use-loop-for-minmax-instead-of-sort) - 7.12 [Use Set/Map for O(1) Lookups](#712-use-setmap-for-o1-lookups) - 7.13 [Use toSorted() Instead of sort() for Immutability](#713-use-tosorted-instead-of-sort-for-immutability) 8. [Advanced Patterns](#8-advanced-patterns) — **LOW** - 8.1 [Initialize App Once, Not Per Mount](#81-initialize-app-once-not-per-mount) - 8.2 [Store Event Handlers in Refs](#82-store-event-handlers-in-refs) - 8.3 [useEffectEvent for Stable Callback Refs](#83-useeffectevent-for-stable-callback-refs) --- ## 1. Eliminating Waterfalls **Impact: CRITICAL** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains. ### 1.1 Defer Await Until Needed **Impact: HIGH (avoids blocking unused code paths)** Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them. **Incorrect: blocks both branches** ```typescript async function handleRequest(userId: string, skipProcessing: boolean) { const userData = await fetchUserData(userId) if (skipProcessing) { // Returns immediately but still waited for userData return { skipped: true } } // Only this branch uses userData return processUserData(userData) } ``` **Correct: only blocks when needed** ```typescript async function handleRequest(userId: string, skipProcessing: boolean) { if (skipProcessing) { // Returns immediately without waiting return { skipped: true } } // Fetch only when needed const userData = await fetchUserData(userId) return processUserData(userData) } ``` **Another example: early return optimization** ```typescript // Incorrect: always fetches permissions async function updateResource(resourceId: string, userId: string) { const permissions = await fetchPermissions(userId) const resource = await getResource(resourceId) if (!resource) { return { error: 'Not found' } } if (!permissions.canEdit) { return { error: 'Forbidden' } } return await updateResourceData(resource, permissions) } // Correct: fetches only when needed async function updateResource(resourceId: string, userId: string) { const resource = await getResource(resourceId) if (!resource) { return { error: 'Not found' } } const permissions = await fetchPermissions(userId) if (!permissions.canEdit) { return { error: 'Forbidden' } } return await updateResourceData(resource, permissions) } ``` This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive. ### 1.2 Dependency-Based Parallelization **Impact: CRITICAL (2-10× improvement)** For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment. **Incorrect: profile waits for config unnecessarily** ```typescript const [user, config] = await Promise.all([ fetchUser(), fetchConfig() ]) const profile = await fetchProfile(user.id) ``` **Correct: config and profile run in parallel** ```typescript import { all } from 'better-all' const { user, config, profile } = await all({ async user() { return fetchUser() }, async config() { return fetchConfig() }, async profile() { return fetchProfile((await this.$.user).id) } }) ``` **Alternative without extra dependencies:** ```typescript const userPromise = fetchUser() const profilePromise = userPromise.then(user => fetchProfile(user.id)) const [user, config, profile] = await Promise.all([ userPromise, fetchConfig(), profilePromise ]) ``` We can also create all the promises first, and do `Promise.all()` at the end. Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all) ### 1.3 Prevent Waterfall Chains in API Routes **Impact: CRITICAL (2-10× improvement)** In API routes and Server Actions, start independent operations immediately, even if you don't await them yet. **Incorrect: config waits for auth, data waits for both** ```typescript export async function GET(request: Request) { const session = await auth() const config = await fetchConfig() const data = await fetchData(session.user.id) return Response.json({ data, config }) } ``` **Correct: auth and config start immediately** ```typescript export async function GET(request: Request) { const sessionPromise = auth() const configPromise = fetchConfig() const session = await sessionPromise const [config, data] = await Promise.all([ configPromise, fetchData(session.user.id) ]) return Response.json({ data, config }) } ``` For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization). ### 1.4 Promise.all() for Independent Operations **Impact: CRITICAL (2-10× improvement)** When async operations have no interdependencies, execute them concurrently using `Promise.all()`. **Incorrect: sequential execution, 3 round trips** ```typescript const user = await fetchUser() const posts = await fetchPosts() const comments = await fetchComments() ``` **Correct: parallel execution, 1 round trip** ```typescript const [user, posts, comments] = await Promise.all([ fetchUser(), fetchPosts(), fetchComments() ]) ``` ### 1.5 Strategic Suspense Boundaries **Impact: HIGH (faster initial paint)** Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads. **Incorrect: wrapper blocked by data fetching** ```tsx async function Page() { const data = await fetchData() // Blocks entire page return (

Sidebar

Header

Footer

) } ``` The entire layout waits for data even though only the middle section needs it. **Correct: wrapper shows immediately, data streams in** ```tsx function Page() { return (

Sidebar

Header

Footer

) } async function DataDisplay() { const data = await fetchData() // Only blocks this component return

{data.content}

} ``` Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data. **Alternative: share promise across components** ```tsx function Page() { // Start fetch immediately, but don't await const dataPromise = fetchData() return (

Sidebar

Header

Footer

) } function DataDisplay({ dataPromise }: { dataPromise: Promise }) { const data = use(dataPromise) // Unwraps the promise return

{data.content}

} function DataSummary({ dataPromise }: { dataPromise: Promise }) { const data = use(dataPromise) // Reuses the same promise return

{data.summary}

} ``` Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together. **When NOT to use this pattern:** - Critical data needed for layout decisions (affects positioning) - SEO-critical content above the fold - Small, fast queries where suspense overhead isn't worth it - When you want to avoid layout shift (loading → content jump) **Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities. --- ## 2. Bundle Size Optimization **Impact: CRITICAL** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint. ### 2.1 Avoid Barrel File Imports **Impact: CRITICAL (200-800ms import cost, slow builds)** Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`). Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts. **Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph. **Incorrect: imports entire library** ```tsx import { Check, X, Menu } from 'lucide-react' // Loads 1,583 modules, takes ~2.8s extra in dev // Runtime cost: 200-800ms on every cold start import { Button, TextField } from '@mui/material' // Loads 2,225 modules, takes ~4.2s extra in dev ``` **Correct: imports only what you need** ```tsx import Check from 'lucide-react/dist/esm/icons/check' import X from 'lucide-react/dist/esm/icons/x' import Menu from 'lucide-react/dist/esm/icons/menu' // Loads only 3 modules (~2KB vs ~1MB) import Button from '@mui/material/Button' import TextField from '@mui/material/TextField' // Loads only what you use ``` **Alternative: Next.js 13.5+** ```js // next.config.js - use optimizePackageImports module.exports = { experimental: { optimizePackageImports: ['lucide-react', '@mui/material'] } } // Then you can keep the ergonomic barrel imports: import { Check, X, Menu } from 'lucide-react' // Automatically transformed to direct imports at build time ``` Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR. Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`. Reference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js) ### 2.2 Conditional Module Loading **Impact: HIGH (loads large data only when needed)** Load large data or modules only when a feature is activated. **Example: lazy-load animation frames** ```tsx function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch> }) { const [frames, setFrames] = useState(null) useEffect(() => { if (enabled && !frames && typeof window !== 'undefined') { import('./animation-frames.js') .then(mod => setFrames(mod.frames)) .catch(() => setEnabled(false)) } }, [enabled, frames, setEnabled]) if (!frames) return return

React Best Practices Cn

Comments (0)