Vercel React Best Practices (Local/Docker)

Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. This version highlights the most important patterns for local installs or dockerized deployments.

Purpose

Provide a high-signal checklist to avoid async waterfalls, reduce client payloads, and keep UI responsive without relying on hosted or edge-specific optimizations.

When to Apply

• Building or refactoring React components or Next.js pages

• Implementing Server Actions, Route Handlers, or data fetching

• Reducing startup time or memory footprint for local installs

• Debugging sluggish UI or long hydration times

• Reviewing code for performance regressions

Offline and Docker Focus

• Optimize for cold-start and steady-state responsiveness over SEO.

• Use in-process caches because the server process persists.

• Avoid sequential awaits even for local APIs or databases.

• Defer non-critical work until after render or after responses are sent.

• Minimize RSC props to reduce hydration and memory overhead.

Top Findings

• Eliminate async waterfalls by starting work early and awaiting late with Promise.all or better-all .

• Use Suspense boundaries to stream UI instead of blocking the whole page on data.

• Reduce initial load and memory via dynamic imports, conditional loading, and direct imports.

• Minimize RSC payloads; pass only fields used and avoid duplicating serialized data.

• Cache hot server work: React.cache per request and LRU for cross-request reuse.

• Reduce client work with memoized subtrees, lazy state init, transitions, and content-visibility for large lists.

Core Patterns

• async-parallel and async-api-routes to eliminate waterfalls

• async-suspense-boundaries to stream slow sections

• bundle-barrel-imports and bundle-dynamic-imports to reduce startup cost

• server-serialization and server-dedup-props to shrink RSC payloads

• server-cache-react and server-cache-lru to reuse hot work

• rerender-lazy-state-init and rerender-transitions for responsive UI

• rendering-content-visibility for long lists

• client-swr-dedup for fetch deduplication

Outputs

• REACT_PATTERNS.md for a condensed, offline-focused guide

• AGENT.md for the full compiled reference

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-

How to Use

Start with REACT_PATTERNS.md for the condensed guidance.

Full Compiled Document

For the complete guide with all rules expanded: AGENT.md