react-best-practices（React 最佳实践）

React & Next.js Performance Patterns

Performance optimization guide for React and Next.js applications, based on Vercel Engineering practices. 8 categories organized by impact.

When to Apply

• Writing new React components or Next.js pages
• Implementing data fetching (client or server-side)
• Reviewing code for performance issues
• Optimizing bundle size or load times

Quick Reference

1. Async Patterns (CRITICAL)

references/async-patterns.md

• Prevent waterfall chains in API routes -- start promises early, await late
• Defer await until needed -- move await into branches that use it
• Dependency-based parallelization -- Promise.all() with .then() chaining
• Strategic Suspense boundaries -- stream content with <Suspense>

2. Bundle Optimization (CRITICAL)

references/bundle-optimization.md

• Avoid barrel file imports -- import directly from source files
• Conditional module loading -- load only when feature is activated
• Defer non-critical third-party libraries -- load after hydration
• Dynamic imports for heavy components -- next/dynamic with ssr: false
• Preload on user intent -- preload on hover/focus

3. Server-Side Performance (HIGH)

references/server-performance.md

• after() for non-blocking operations -- logging, analytics after response
• Authenticate Server Actions -- treat as public endpoints
• Cross-request LRU caching -- share data across sequential requests
• React.cache() deduplication -- per-request with primitive args
• Avoid duplicate RSC serialization -- transform in client, not server
• Parallel fetching via composition -- restructure component tree
• Minimize serialization at boundaries -- pass only needed fields

4. Client-Side Patterns (MEDIUM-HIGH)

references/client-patterns.md

• Deduplicate global event listeners -- useSWRSubscription
• Version and minimize localStorage -- schema versioning, try-catch
• Passive event listeners -- {passive: true} for scroll performance
• SWR for automatic deduplication -- caching and revalidation

5. Re-render Optimization (MEDIUM)

references/rerender-optimization.md

• Defer state reads to usage point -- read in callbacks, not render
• Narrow effect dependencies -- use primitives, not objects
• Derive state during render -- no state + effect for computed values
• Functional setState -- stable callbacks, no stale closures
• Hoist default non-primitive props -- stable defaults for memo()
• Extract to memoized components -- skip computation with early returns
• Interaction logic in event handlers -- not state + effect
• useRef for transient values -- avoid re-render on frequent updates

6. Rendering Performance (MEDIUM)

references/rendering-performance.md

• Animate SVG wrapper -- hardware-accelerated CSS on <div>, not <svg>
• CSS content-visibility: auto -- defer off-screen rendering
• Hoist static JSX -- extract constants outside components
• Prevent hydration mismatch -- inline script for client-only data
• useTransition over manual loading states -- built-in pending state

7. JavaScript Performance (LOW-MEDIUM)

references/js-performance.md

• Avoid layout thrashing -- batch DOM reads and writes
• Cache repeated function calls -- module-level Map
• Cache storage API calls -- in-memory cache for localStorage/cookies
• Build index Maps for lookups -- O(1) instead of O(n) .find()
• Loop for min/max -- O(n) instead of O(n log n) sort

8. Advanced Patterns (LOW)

references/advanced-patterns.md

• Store event handlers in refs -- stable effect subscriptions
• Initialize app once per load -- module-level guard