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)
- 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/dynamicwithssr: 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)
- 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
useTransitionover manual loading states -- built-in pending state
7. JavaScript Performance (LOW-MEDIUM)
- 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