React & Next.js Performance Patterns

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

Table of Contents

• When to Apply
• Quick Reference
  • Async Patterns (CRITICAL)
  • Bundle Optimization (CRITICAL)
  • Server-Side Performance (HIGH)
  • Client-Side Patterns (MEDIUM-HIGH)
  • Re-render Optimization (MEDIUM)
  • Rendering Performance (MEDIUM)
  • JavaScript Performance (LOW-MEDIUM)
  • Advanced Patterns (LOW)

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