Next.js & React Performance Expert

From Vercel Engineering - 57 optimization rules prioritized by impact Philosophy: Eliminate waterfalls first, optimize bundles second, then micro-optimize.

🎯 Selective Reading Rule (MANDATORY)

Read ONLY sections relevant to your task! Check the content map below and load what you need.

🔴 For performance reviews: Start with CRITICAL sections (1-2), then move to HIGH/MEDIUM.

📑 Content Map

| File | Impact | Rules | When to Read | | --------------------------------------- | ------------------ | -------- | --------------------------------------------------------------- | | 1-async-eliminating-waterfalls.md | 🔴 CRITICAL | 5 rules | Slow page loads, sequential API calls, data fetching waterfalls | | 2-bundle-bundle-size-optimization.md | 🔴 CRITICAL | 5 rules | Large bundle size, slow Time to Interactive, First Load issues | | 3-server-server-side-performance.md | 🟠 HIGH | 7 rules | Slow SSR, API route optimization, server-side waterfalls | | 4-client-client-side-data-fetching.md | 🟡 MEDIUM-HIGH | 4 rules | Client data management, SWR patterns, deduplication | | 5-rerender-re-render-optimization.md | 🟡 MEDIUM | 12 rules | Excessive re-renders, React performance, memoization | | 6-rendering-rendering-performance.md | 🟡 MEDIUM | 9 rules | Rendering bottlenecks, virtualization, image optimization | | 7-js-javascript-performance.md | ⚪ LOW-MEDIUM | 12 rules | Micro-optimizations, caching, loop performance | | 8-advanced-advanced-patterns.md | 🔵 VARIABLE | 3 rules | Advanced React patterns, useLatest, init-once |

Total: 57 rules across 8 categories

🚀 Quick Decision Tree

What's your performance issue?

🐌 Slow page loads / Long Time to Interactive
  → Read Section 1: Eliminating Waterfalls
  → Read Section 2: Bundle Size Optimization

📦 Large bundle size (> 200KB)
  → Read Section 2: Bundle Size Optimization
  → Check: Dynamic imports, barrel imports, tree-shaking

🖥️ Slow Server-Side Rendering
  → Read Section 3: Server-Side Performance
  → Check: Parallel data fetching, streaming

🔄 Too many re-renders / UI lag
  → Read Section 5: Re-render Optimization
  → Check: React.memo, useMemo, useCallback

🎨 Rendering performance issues
  → Read Section 6: Rendering Performance
  → Check: Virtualization, layout thrashing

🌐 Client-side data fetching problems
  → Read Section 4: Client-Side Data Fetching
  → Check: SWR deduplication, localStorage

✨ Need advanced patterns
  → Read Section 8: Advanced Patterns

📊 Impact Priority Guide

Use this order when doing comprehensive optimization:

1️⃣ CRITICAL (Biggest Gains - Do First):
   ├─ Section 1: Eliminating Waterfalls
   │  └─ Each waterfall adds full network latency (100-500ms+)
   └─ Section 2: Bundle Size Optimization
      └─ Affects Time to Interactive and Largest Contentful Paint

2️⃣ HIGH (Significant Impact - Do Second):
   └─ Section 3: Server-Side Performance
      └─ Eliminates server-side waterfalls, faster response times

3️⃣ MEDIUM (Moderate Gains - Do Third):
   ├─ Section 4: Client-Side Data Fetching
   ├─ Section 5: Re-render Optimization
   └─ Section 6: Rendering Performance

4️⃣ LOW (Polish - Do Last):
   ├─ Section 7: JavaScript Performance
   └─ Section 8: Advanced Patterns

🔗 Related Skills

| Need | Skill | | ----------------------- | --------------------------------- | | API design patterns | @[skills/api-patterns] | | Database optimization | @[skills/database-design] | | Testing strategies | @[skills/testing-patterns] | | UI/UX design principles | @[skills/frontend-design] | | TypeScript patterns | @[skills/typescript-expert] | | Deployment & DevOps | @[skills/deployment-procedures] |

✅ Performance Review Checklist

Before shipping to production:

Critical (Must Fix):

[ ] No sequential data fetching (waterfalls eliminated)
[ ] Bundle size < 200KB for main bundle
[ ] No barrel imports in app code
[ ] Dynamic imports used for large components
[ ] Parallel data fetching where possible

High Priority:

[ ] Server components used where appropriate
[ ] API routes optimized (no N+1 queries)
[ ] Suspense boundaries for data fetching
[ ] Static generation used where possible

Medium Priority:

[ ] Expensive computations memoized
[ ] List rendering virtualized (if > 100 items)
[ ] Images optimized with next/image
[ ] No unnecessary re-renders

Low Priority (Polish):

[ ] Hot path loops optimized
[ ] RegExp patterns hoisted
[ ] Property access cached in loops

❌ Anti-Patterns (Common Mistakes)

DON'T:

❌ Use sequential await for independent operations
❌ Import entire libraries when you need one function
❌ Use barrel exports (index.ts re-exports) in app code
❌ Skip dynamic imports for large components/libraries
❌ Fetch data in useEffect without deduplication
❌ Forget to memoize expensive computations
❌ Use client components when server components work

DO:

✅ Fetch data in parallel with Promise.all()
✅ Use dynamic imports: const Comp = dynamic(() => import('./Heavy'))
✅ Import directly: import { specific } from 'library/specific'
✅ Use Suspense boundaries for better UX
✅ Leverage React Server Components
✅ Measure performance before optimizing
✅ Use Next.js built-in optimizations (next/image, next/font)

🎯 How to Use This Skill

For New Features:

Check Section 1 & 2 while building (prevent waterfalls, keep bundle small)
Use server components by default (Section 3)
Apply memoization for expensive operations (Section 5)

For Performance Reviews:

Start with Section 1 (waterfalls = biggest impact)
Then Section 2 (bundle size)
Then Section 3 (server-side)
Finally other sections as needed

For Debugging Slow Performance:

Identify the symptom (slow load, lag, etc.)
Use Quick Decision Tree above
Read relevant section
Apply fixes in priority order

📚 Learning Path

Beginner (Focus on Critical): → Section 1: Eliminating Waterfalls → Section 2: Bundle Size Optimization

Intermediate (Add High Priority): → Section 3: Server-Side Performance → Section 5: Re-render Optimization

Advanced (Full Optimization): → All sections + Section 8: Advanced Patterns

🔍 Validation Script

| Script | Purpose | Command | | -------------------------------------- | --------------------------- | ------------------------------------------------------------ | | scripts/react_performance_checker.py | Automated performance audit | python scripts/react_performance_checker.py <project_path> |

📖 Section Details

Section 1: Eliminating Waterfalls (CRITICAL)

Impact: Each waterfall adds 100-500ms+ latency Key Concepts: Parallel fetching, Promise.all(), Suspense boundaries, preloading

Section 2: Bundle Size Optimization (CRITICAL)

Impact: Directly affects Time to Interactive, Largest Contentful Paint Key Concepts: Dynamic imports, tree-shaking, barrel import avoidance

Section 3: Server-Side Performance (HIGH)

Impact: Faster server responses, better SEO Key Concepts: Parallel server fetching, streaming, API route optimization

Section 4: Client-Side Data Fetching (MEDIUM-HIGH)

Impact: Reduces redundant requests, better UX Key Concepts: SWR deduplication, localStorage caching, event listeners

Section 5: Re-render Optimization (MEDIUM)

Impact: Smoother UI, less wasted computation Key Concepts: React.memo, useMemo, useCallback, component structure

Section 6: Rendering Performance (MEDIUM)

Impact: Better rendering efficiency Key Concepts: Virtualization, image optimization, layout thrashing

Section 7: JavaScript Performance (LOW-MEDIUM)

Impact: Incremental improvements in hot paths Key Concepts: Loop optimization, caching, RegExp hoisting

Section 8: Advanced Patterns (VARIABLE)

Impact: Specific use cases Key Concepts: useLatest hook, init-once patterns, event handler refs

🎓 Best Practices Summary

Golden Rules:

Measure first - Use React DevTools Profiler, Chrome DevTools
Biggest impact first - Waterfalls → Bundle → Server → Micro
Don't over-optimize - Focus on real bottlenecks
Use platform features - Next.js has optimizations built-in
Think about users - Real-world conditions matter

Performance Mindset:

Every await in sequence = potential waterfall
Every import = potential bundle bloat
Every re-render = wasted computation (if unnecessary)
Server components = less JavaScript to ship
Measure, don't guess

Source: Vercel Engineering Date: January 2026 Version: 1.0.0 Total Rules: 57 across 8 categories

Next.js & React Performance Expert

From Vercel Engineering - 57 optimization rules prioritized by impact Philosophy: Eliminate waterfalls first, optimize bundles second, then micro-optimize.

🎯 Selective Reading Rule (MANDATORY)

Read ONLY sections relevant to your task! Check the content map below and load what you need.

🔴 For performance reviews: Start with CRITICAL sections (1-2), then move to HIGH/MEDIUM.

📑 Content Map

Total: 57 rules across 8 categories

🚀 Quick Decision Tree

What's your performance issue?

🐌 Slow page loads / Long Time to Interactive
  → Read Section 1: Eliminating Waterfalls
  → Read Section 2: Bundle Size Optimization

📦 Large bundle size (> 200KB)
  → Read Section 2: Bundle Size Optimization
  → Check: Dynamic imports, barrel imports, tree-shaking

🖥️ Slow Server-Side Rendering
  → Read Section 3: Server-Side Performance
  → Check: Parallel data fetching, streaming

🔄 Too many re-renders / UI lag
  → Read Section 5: Re-render Optimization
  → Check: React.memo, useMemo, useCallback

🎨 Rendering performance issues
  → Read Section 6: Rendering Performance
  → Check: Virtualization, layout thrashing

🌐 Client-side data fetching problems
  → Read Section 4: Client-Side Data Fetching
  → Check: SWR deduplication, localStorage

✨ Need advanced patterns
  → Read Section 8: Advanced Patterns

📊 Impact Priority Guide

Use this order when doing comprehensive optimization:

1️⃣ CRITICAL (Biggest Gains - Do First):
   ├─ Section 1: Eliminating Waterfalls
   │  └─ Each waterfall adds full network latency (100-500ms+)
   └─ Section 2: Bundle Size Optimization
      └─ Affects Time to Interactive and Largest Contentful Paint

2️⃣ HIGH (Significant Impact - Do Second):
   └─ Section 3: Server-Side Performance
      └─ Eliminates server-side waterfalls, faster response times

3️⃣ MEDIUM (Moderate Gains - Do Third):
   ├─ Section 4: Client-Side Data Fetching
   ├─ Section 5: Re-render Optimization
   └─ Section 6: Rendering Performance

4️⃣ LOW (Polish - Do Last):
   ├─ Section 7: JavaScript Performance
   └─ Section 8: Advanced Patterns

🔗 Related Skills

✅ Performance Review Checklist

Before shipping to production:

Critical (Must Fix):

[ ] No sequential data fetching (waterfalls eliminated)
[ ] Bundle size < 200KB for main bundle
[ ] No barrel imports in app code
[ ] Dynamic imports used for large components
[ ] Parallel data fetching where possible

High Priority:

[ ] Server components used where appropriate
[ ] API routes optimized (no N+1 queries)
[ ] Suspense boundaries for data fetching
[ ] Static generation used where possible

Medium Priority:

[ ] Expensive computations memoized
[ ] List rendering virtualized (if > 100 items)
[ ] Images optimized with next/image
[ ] No unnecessary re-renders

Low Priority (Polish):

[ ] Hot path loops optimized
[ ] RegExp patterns hoisted
[ ] Property access cached in loops

❌ Anti-Patterns (Common Mistakes)

DON'T:

❌ Use sequential await for independent operations
❌ Import entire libraries when you need one function
❌ Use barrel exports (index.ts re-exports) in app code
❌ Skip dynamic imports for large components/libraries
❌ Fetch data in useEffect without deduplication
❌ Forget to memoize expensive computations
❌ Use client components when server components work

DO:

✅ Fetch data in parallel with Promise.all()
✅ Use dynamic imports: const Comp = dynamic(() => import('./Heavy'))
✅ Import directly: import { specific } from 'library/specific'
✅ Use Suspense boundaries for better UX
✅ Leverage React Server Components
✅ Measure performance before optimizing
✅ Use Next.js built-in optimizations (next/image, next/font)

🎯 How to Use This Skill

For New Features:

Check Section 1 & 2 while building (prevent waterfalls, keep bundle small)
Use server components by default (Section 3)
Apply memoization for expensive operations (Section 5)

For Performance Reviews:

Start with Section 1 (waterfalls = biggest impact)
Then Section 2 (bundle size)
Then Section 3 (server-side)
Finally other sections as needed

For Debugging Slow Performance:

Identify the symptom (slow load, lag, etc.)
Use Quick Decision Tree above
Read relevant section
Apply fixes in priority order

📚 Learning Path

Beginner (Focus on Critical): → Section 1: Eliminating Waterfalls → Section 2: Bundle Size Optimization

Intermediate (Add High Priority): → Section 3: Server-Side Performance → Section 5: Re-render Optimization

Advanced (Full Optimization): → All sections + Section 8: Advanced Patterns

🔍 Validation Script

📖 Section Details

Section 1: Eliminating Waterfalls (CRITICAL)

Impact: Each waterfall adds 100-500ms+ latency Key Concepts: Parallel fetching, Promise.all(), Suspense boundaries, preloading

Section 2: Bundle Size Optimization (CRITICAL)

Impact: Directly affects Time to Interactive, Largest Contentful Paint Key Concepts: Dynamic imports, tree-shaking, barrel import avoidance

Section 3: Server-Side Performance (HIGH)

Impact: Faster server responses, better SEO Key Concepts: Parallel server fetching, streaming, API route optimization

Section 4: Client-Side Data Fetching (MEDIUM-HIGH)

Impact: Reduces redundant requests, better UX Key Concepts: SWR deduplication, localStorage caching, event listeners

Section 5: Re-render Optimization (MEDIUM)

Impact: Smoother UI, less wasted computation Key Concepts: React.memo, useMemo, useCallback, component structure

Section 6: Rendering Performance (MEDIUM)

Impact: Better rendering efficiency Key Concepts: Virtualization, image optimization, layout thrashing

Section 7: JavaScript Performance (LOW-MEDIUM)

Impact: Incremental improvements in hot paths Key Concepts: Loop optimization, caching, RegExp hoisting

Section 8: Advanced Patterns (VARIABLE)

Impact: Specific use cases Key Concepts: useLatest hook, init-once patterns, event handler refs

🎓 Best Practices Summary

Golden Rules:

Measure first - Use React DevTools Profiler, Chrome DevTools
Biggest impact first - Waterfalls → Bundle → Server → Micro
Don't over-optimize - Focus on real bottlenecks
Use platform features - Next.js has optimizations built-in
Think about users - Real-world conditions matter

Performance Mindset:

Every await in sequence = potential waterfall
Every import = potential bundle bloat
Every re-render = wasted computation (if unnecessary)
Server components = less JavaScript to ship
Measure, don't guess

Source: Vercel Engineering Date: January 2026 Version: 1.0.0 Total Rules: 57 across 8 categories

Adoption

JoelBonito/nextjs-react-expert

$ install --global

Security Scan Results

SKILL.md

Next.js & React Performance Expert

🎯 Selective Reading Rule (MANDATORY)

📑 Content Map

🚀 Quick Decision Tree

📊 Impact Priority Guide

🔗 Related Skills

✅ Performance Review Checklist

❌ Anti-Patterns (Common Mistakes)

🎯 How to Use This Skill

For New Features:

For Performance Reviews:

For Debugging Slow Performance:

📚 Learning Path

🔍 Validation Script

📖 Section Details

Section 1: Eliminating Waterfalls (CRITICAL)

Section 2: Bundle Size Optimization (CRITICAL)

Section 3: Server-Side Performance (HIGH)

Section 4: Client-Side Data Fetching (MEDIUM-HIGH)

Section 5: Re-render Optimization (MEDIUM)

Section 6: Rendering Performance (MEDIUM)

Section 7: JavaScript Performance (LOW-MEDIUM)

Section 8: Advanced Patterns (VARIABLE)

🎓 Best Practices Summary

Related Skills

JoelBonito/n8n-orchestration

JoelBonito/squads/.templates/specialist/skills/example

JoelBonito/webapp-testing

JoelBonito/web-design-guidelines

JoelBonito/nextjs-react-expert

$ install --global

Security Scan Results

SKILL.md

Next.js & React Performance Expert

🎯 Selective Reading Rule (MANDATORY)

📑 Content Map

🚀 Quick Decision Tree

📊 Impact Priority Guide

🔗 Related Skills

✅ Performance Review Checklist

❌ Anti-Patterns (Common Mistakes)

🎯 How to Use This Skill

For New Features:

For Performance Reviews:

For Debugging Slow Performance:

📚 Learning Path

🔍 Validation Script

📖 Section Details

Section 1: Eliminating Waterfalls (CRITICAL)

Section 2: Bundle Size Optimization (CRITICAL)

Section 3: Server-Side Performance (HIGH)

Section 4: Client-Side Data Fetching (MEDIUM-HIGH)

Section 5: Re-render Optimization (MEDIUM)

Section 6: Rendering Performance (MEDIUM)

Section 7: JavaScript Performance (LOW-MEDIUM)

Section 8: Advanced Patterns (VARIABLE)

🎓 Best Practices Summary

Related Skills

JoelBonito/n8n-orchestration

JoelBonito/squads/.templates/specialist/skills/example

JoelBonito/webapp-testing

JoelBonito/web-design-guidelines