react-best-practices

来自 Vercel 工程团队的 React 和 Next.js 性能优化指南。在编写、审查或重构 React/Next.js 代码时，此技能应被优先选用，以确保代码始终运行在最优性能模式下。它会在涉及 React 组件、Next.js 页面、数据获取、包体积优化，或性能提升等任务时自动触发。

SKILL.md

--- frontmatter

name: react-best-practices
description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
allowed-tools: Read, Glob, Grep

React Best Practices - Vercel Engineering

Performance optimization guide for React and Next.js applications. Contains 45 rules across 8 categories, prioritized by impact.

Core skill for: [[Dev]] (implementing React/Next.js code) and [[Architect]] (designing React architectures).

Core Principle

Performance is a feature. Apply these patterns when writing or reviewing React/Next.js code to prevent performance regressions before they ship.

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

Auto-Detection

This skill auto-activates when working with:

•Files matching *.tsx, *.jsx, components/**, pages/**, app/**
•Imports from react, next, next/dynamic, swr
•Patterns like useState, useEffect, getServerSideProps, use client

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-defer-await - Move await into branches where actually used
•async-parallel - Use Promise.all() for independent operations
•async-dependencies - Use better-all for partial dependencies
•async-api-routes - Start promises early, await late in API routes
•async-suspense-boundaries - Use Suspense to stream content

2. Bundle Size Optimization (CRITICAL)

•bundle-barrel-imports - Import directly, avoid barrel files
•bundle-dynamic-imports - Use next/dynamic for heavy components
•bundle-defer-third-party - Load analytics/logging after hydration
•bundle-conditional - Load modules only when feature is activated
•bundle-preload - Preload on hover/focus for perceived speed

3. Server-Side Performance (HIGH)

•server-cache-react - Use React.cache() for per-request deduplication
•server-cache-lru - Use LRU cache for cross-request caching
•server-serialization - Minimize data passed to client components
•server-parallel-fetching - Restructure components to parallelize fetches
•server-after-nonblocking - Use after() for non-blocking operations

4. Client-Side Data Fetching (MEDIUM-HIGH)

•client-swr-dedup - Use SWR for automatic request deduplication
•client-event-listeners - Deduplicate global event listeners

5. Re-render Optimization (MEDIUM)

•rerender-defer-reads - Don't subscribe to state only used in callbacks
•rerender-memo - Extract expensive work into memoized components
•rerender-dependencies - Use primitive dependencies in effects
•rerender-derived-state - Subscribe to derived booleans, not raw values
•rerender-functional-setstate - Use functional setState for stable callbacks
•rerender-lazy-state-init - Pass function to useState for expensive values
•rerender-transitions - Use startTransition for non-urgent updates

6. Rendering Performance (MEDIUM)

•rendering-animate-svg-wrapper - Animate div wrapper, not SVG element
•rendering-content-visibility - Use content-visibility for long lists
•rendering-hoist-jsx - Extract static JSX outside components
•rendering-svg-precision - Reduce SVG coordinate precision
•rendering-hydration-no-flicker - Use inline script for client-only data
•rendering-activity - Use Activity component for show/hide
•rendering-conditional-render - Use ternary, not && for conditionals

7. JavaScript Performance (LOW-MEDIUM)

•js-batch-dom-css - Group CSS changes via classes or cssText
•js-index-maps - Build Map for repeated lookups
•js-cache-property-access - Cache object properties in loops
•js-cache-function-results - Cache function results in module-level Map
•js-cache-storage - Cache localStorage/sessionStorage reads
•js-combine-iterations - Combine multiple filter/map into one loop
•js-length-check-first - Check array length before expensive comparison
•js-early-exit - Return early from functions
•js-hoist-regexp - Hoist RegExp creation outside loops
•js-min-max-loop - Use loop for min/max instead of sort
•js-set-map-lookups - Use Set/Map for O(1) lookups
•js-tosorted-immutable - Use toSorted() for immutability

8. Advanced Patterns (LOW)

•advanced-event-handler-refs - Store event handlers in refs
•advanced-use-latest - useLatest for stable callback refs

How to Use

Quick lookup: Reference the rule name from the Quick Reference above, then read the detailed rule:

code

rules/{rule-name}.md

Example: For async-parallel, read rules/async-parallel.md

Each rule file contains:

•Brief explanation of why it matters
•Incorrect code example with explanation
•Correct code example with explanation
•Additional context and references

Full document: For the complete guide with all rules expanded: AGENTS.md

Integration with Orchestrators

Implementation (auto-dev)

When implementing React/Next.js tasks:

•Check applicable rules before writing code
•Apply CRITICAL rules (async-, bundle-) by default
•Reference specific rules when reviewing implementations

Architect (Archie)

When designing React architectures:

•Use rules to inform ADR decisions
•Reference specific patterns in architecture documentation
•Include rule citations in design rationale