--- name: react-best-practices description: React and Next.js performance optimization patterns. Use BEFORE implementing any React code to ensure best practices are followed. --- # React Best Practices **Version 1.0.0** Source: Vercel Engineering (vercel-labs\/agent-skills) > **Note:** > This document is for agents and LLMs to follow when maintaining, > generating, or refactoring React and Next.js codebases. Contains 40+ rules across 8 categories, prioritized by impact. --- ## How to Use This Skill **Before implementing ANY React\/Next.js code:** 1. Review the relevant sections based on what you're building 2. Apply the patterns as you write code 3. Use the "Incorrect" vs "Correct" examples as templates **Priority order:** Eliminating Waterfalls > Bundle Size > Server-Side > Client-Side > Re-renders > Rendering > JS Perf > Advanced --- ## Quick Reference: Critical Rules ### Top 5 Rules (Always Apply) 1. **Promise.all() for independent operations** - Never sequential awaits for independent data 2. **Avoid barrel file imports** - Import directly from source files 3. **Dynamic imports for heavy components** - Lazy-load Monaco, charts, etc. 4. **Parallel data fetching with component composition** - Structure RSC for parallelism 5. **Minimize serialization at RSC boundaries** - Only pass needed fields to client --- ## 1. Eliminating Waterfalls **Impact: CRITICAL** - Waterfalls are the #1 performance killer. ### 1.1 Defer Await Until Needed Move `await` into branches where actually used. ```typescript \/\/ BAD: blocks both branches async function handleRequest(userId: string, skipProcessing: boolean) { const userData = await fetchUserData(userId) if (skipProcessing) return { skipped: true } return processUserData(userData) } \/\/ GOOD: only blocks when needed async function handleRequest(userId: string, skipProcessing: boolean) { if (skipProcessing) return { skipped: true } const userData = await fetchUserData(userId) return processUserData(userData) } ``` ### 1.2 Promise.all() for Independent Operations ```typescript \/\/ BAD: 3 round trips const user = await fetchUser() const posts = await fetchPosts() const comments = await fetchComments() \/\/ GOOD: 1 round trip const [user, posts, comments] = await Promise.all([ fetchUser(), fetchPosts(), fetchComments() ]) ``` ### 1.3 Strategic Suspense Boundaries ```tsx \/\/ BAD: wrapper blocked by data async function Page() { const data = await fetchData() return (