详细说明
这份 Skill 的价值在于安排性能审查的顺序。当前固定版本把 70 条规则分为八类,将请求瀑布和包体积列为最高优先级,再覆盖服务端工作、客户端取数、重复渲染、渲染过程、JavaScript 和进阶模式。检查一个页面时,可以先找依赖关系和加载工作带来的成本,再决定是否值得调整较小的局部写法。
SKILL.md 是入口索引,具体解释分布在 rules/ 目录的规则文件中,AGENTS.md 则提供展开后的完整指南。规则文件会说明问题并给出正反代码示例,例如 async-parallel 讨论独立操作的并行处理,bundle-barrel-imports 关注导入结构。应用建议前应打开对应说明,结合组件的数据依赖、鉴权边界和框架版本判断,不能只凭优先级标签决定改代码。
需要准备什么
- 项目使用的 React 或 Next.js 版本、相关页面与组件文件,以及希望检查的具体任务。
- 与该任务关联的数据请求和导入代码;已有的包体积分析或性能诊断可一并提供。
- 必须保留的行为,包括请求依赖、服务端与客户端边界、用户权限要求。
可以得到什么
- 对应具体规则及影响分类的代码审查建议。
- 用于判断改动是否合适的代码模式和规则文件示例。
- 需要结合项目构建、行为检查和性能测量验证的候选优化项。
使用步骤
- 明确目标页面或组件、框架版本,以及要排查的行为或加载问题。
- 先查看请求瀑布和包体积类别,再检查与当前代码相关的其他规则。
- 打开对应规则文件或 AGENTS.md 中的展开说明,不只阅读入口的一句话索引。
- 核对建议是否符合实际依赖、请求作用域、用户权限和可用 API。
- 如需在自己的项目中改代码,逐项进行小范围调整,并在相同条件下比较行为和已有诊断结果。
限制与检查
- 被并行处理的操作确实独立,必要的数据与鉴权顺序没有被打乱。
- 导入和延迟加载调整符合组件的服务端或客户端边界。
- 缓存不会引入跨请求共享的可变状态,也不会混用不同用户的数据。
- 项目实际支持所选规则中涉及的 React 或 Next.js API。
- 改动经过测试和测量验证,不能把规则的影响标签当成已经测出的性能收益。
常见问题
只有 Next.js 项目才适用吗?
来源同时覆盖 React 与 Next.js。组件状态、重复渲染和 JavaScript 等规则可用于相关 React 代码;服务端操作及其他框架专属模式需要对应环境。应选择适用的规则,不必把整份清单当成所有项目都必须完成的改造任务。
只复制 SKILL.md 就够了吗?
入口文档会引用单独的规则文件和展开后的 AGENTS.md。应让助手能够读取完整 Skill 包,才能查看索引背后的解释与代码示例。
它会直接给出项目的性能分数吗?
这套资料提供规则和示例,并没有测量你的项目。需要使用自己的构建与诊断工具,在一致条件下比较修改前后的结果。
安装这个 Skill
通过 Skills CLI,从已验证的 GitHub 来源添加这个 Skill。
npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices来源信息
按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。
Vercel React Best Practices
Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
When to Apply
Reference these guidelines when:
- Writing new React components or Next.js pages
- Implementing data fetching (client or server-side)
- Reviewing code for performance issues
- Refactoring existing React/Next.js code
- Optimizing bundle size or load times
Rule Categories by Priority
| 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- |
Quick Reference
1. Eliminating Waterfalls (CRITICAL)
async-cheap-condition-before-await- Check cheap sync conditions before awaiting flags or remote valuesasync-defer-await- Move await into branches where actually usedasync-parallel- Use Promise.all() for independent operationsasync-dependencies- Use better-all for partial dependenciesasync-api-routes- Start promises early, await late in API routesasync-suspense-boundaries- Use Suspense to stream content
2. Bundle Size Optimization (CRITICAL)
bundle-barrel-imports- Import directly, avoid barrel filesbundle-analyzable-paths- Prefer statically analyzable import and file-system paths to avoid broad bundles and tracesbundle-dynamic-imports- Use next/dynamic for heavy componentsbundle-defer-third-party- Load analytics/logging after hydrationbundle-conditional- Load modules only when feature is activatedbundle-preload- Preload on hover/focus for perceived speed
3. Server-Side Performance (HIGH)
server-auth-actions- Authenticate server actions like API routesserver-cache-react- Use React.cache() for per-request deduplicationserver-cache-lru- Use LRU cache for cross-request cachingserver-dedup-props- Avoid duplicate serialization in RSC propsserver-hoist-static-io- Hoist static I/O (fonts, logos) to module levelserver-no-shared-module-state- Avoid module-level mutable request state in RSC/SSRserver-serialization- Minimize data passed to client componentsserver-parallel-fetching- Restructure components to parallelize fetchesserver-parallel-nested-fetching- Chain nested fetches per item in Promise.allserver-after-nonblocking- Use after() for non-blocking operations
4. Client-Side Data Fetching (MEDIUM-HIGH)
client-swr-dedup- Use SWR for automatic request deduplicationclient-event-listeners- Deduplicate global event listenersclient-passive-event-listeners- Use passive listeners for scrollclient-localstorage-schema- Version and minimize localStorage data
5. Re-render Optimization (MEDIUM)
rerender-defer-reads- Don't subscribe to state only used in callbacksrerender-memo- Extract expensive work into memoized componentsrerender-memo-with-default-value- Hoist default non-primitive propsrerender-dependencies- Use primitive dependencies in effectsrerender-derived-state- Subscribe to derived booleans, not raw valuesrerender-derived-state-no-effect- Derive state during render, not effectsrerender-functional-setstate- Use functional setState for stable callbacksrerender-lazy-state-init- Pass function to useState for expensive valuesrerender-simple-expression-in-memo- Avoid memo for simple primitivesrerender-split-combined-hooks- Split hooks with independent dependenciesrerender-move-effect-to-event- Put interaction logic in event handlersrerender-transitions- Use startTransition for non-urgent updatesrerender-use-deferred-value- Defer expensive renders to keep input responsivererender-use-ref-transient-values- Use refs for transient frequent valuesrerender-no-inline-components- Don't define components inside components
6. Rendering Performance (MEDIUM)
rendering-animate-svg-wrapper- Animate div wrapper, not SVG elementrendering-content-visibility- Use content-visibility for long listsrendering-hoist-jsx- Extract static JSX outside componentsrendering-svg-precision- Reduce SVG coordinate precisionrendering-hydration-no-flicker- Use inline script for client-only datarendering-hydration-suppress-warning- Suppress expected mismatchesrendering-activity- Use Activity component for show/hiderendering-conditional-render- Use ternary, not && for conditionalsrendering-usetransition-loading- Prefer useTransition for loading staterendering-resource-hints- Use React DOM resource hints for preloadingrendering-script-defer-async- Use defer or async on script tags
7. JavaScript Performance (LOW-MEDIUM)
js-batch-dom-css- Group CSS changes via classes or cssTextjs-index-maps- Build Map for repeated lookupsjs-cache-property-access- Cache object properties in loopsjs-cache-function-results- Cache function results in module-level Mapjs-cache-storage- Cache localStorage/sessionStorage readsjs-combine-iterations- Combine multiple filter/map into one loopjs-length-check-first- Check array length before expensive comparisonjs-early-exit- Return early from functionsjs-hoist-regexp- Hoist RegExp creation outside loopsjs-min-max-loop- Use loop for min/max instead of sortjs-set-map-lookups- Use Set/Map for O(1) lookupsjs-tosorted-immutable- Use toSorted() for immutabilityjs-flatmap-filter- Use flatMap to map and filter in one passjs-request-idle-callback- Defer non-critical work to browser idle time
8. Advanced Patterns (LOW)
advanced-effect-event-deps- Don't putuseEffectEventresults in effect depsadvanced-event-handler-refs- Store event handlers in refsadvanced-init-once- Initialize app once per app loadadvanced-use-latest- useLatest for stable callback refs
How to Use
Read individual rule files for detailed explanations and code examples:
rules/async-parallel.md
rules/bundle-barrel-imports.mdEach rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md

