React Best Practices

Vercel React Best Practices

Measurement-led React and Next.js performance skill for routing slow-page work into the right packet before refactoring. The canonical focus is waterfalls, bundle weight, RSC or client-boundary mistakes, hydration/script cost, and rerender churn; the deep AGENTS.md remains available, but day-to-day use should start from the lighter reference bundle and route-outs.

When to use this skill

Reference these guidelines when:

• Writing new React components or Next.js pages
• Implementing data fetching (client or server-side)
• Reviewing code for performance issues
• Refactoring existing React/Next.js code
• Optimizing bundle size or load times

Rule Categories by Priority

Quick Reference

1. Eliminating Waterfalls (CRITICAL)

• async-defer-await - Move await into branches where actually used
• async-parallel - Use Promise.all() for independent operations
• async-dependencies - Use better-all for partial dependencies
• async-api-routes - Start promises early, await late in API routes
• async-suspense-boundaries - Use Suspense to stream content

2. Bundle Size Optimization (CRITICAL)

• bundle-barrel-imports - Import directly, avoid barrel files
• bundle-dynamic-imports - Use next/dynamic for heavy components
• bundle-defer-third-party - Load analytics/logging after hydration
• bundle-conditional - Load modules only when feature is activated
• bundle-preload - Preload on hover/focus for perceived speed

3. Server-Side Performance (HIGH)

• server-cache-react - Use React.cache() for per-request deduplication
• server-cache-lru - Use LRU cache for cross-request caching
• server-serialization - Minimize data passed to client components
• server-parallel-fetching - Restructure components to parallelize fetches
• server-after-nonblocking - Use after() for non-blocking operations

4. Client-Side Data Fetching (MEDIUM-HIGH)

• client-swr-dedup - Use SWR for automatic request deduplication
• client-event-listeners - Deduplicate global event listeners

5. Re-render Optimization (MEDIUM)

• rerender-defer-reads - Don't subscribe to state only used in callbacks
• rerender-memo - Extract expensive work into memoized components
• rerender-dependencies - Use primitive dependencies in effects
• rerender-derived-state - Subscribe to derived booleans, not raw values
• rerender-functional-setstate - Use functional setState for stable callbacks
• rerender-lazy-state-init - Pass function to useState for expensive values
• rerender-transitions - Use startTransition for non-urgent updates

6. Rendering Performance (MEDIUM)

• rendering-animate-svg-wrapper - Animate div wrapper, not SVG element
• rendering-content-visibility - Use content-visibility for long lists
• rendering-hoist-jsx - Extract static JSX outside components
• rendering-svg-precision - Reduce SVG coordinate precision
• rendering-hydration-no-flicker - Use inline script for client-only data
• rendering-activity - Use Activity component for show/hide
• rendering-conditional-render - Use ternary, not && for conditionals

7. JavaScript Performance (LOW-MEDIUM)

• js-batch-dom-css - Group CSS changes via classes or cssText
• js-index-maps - Build Map for repeated lookups
• js-cache-property-access - Cache object properties in loops
• js-cache-function-results - Cache function results in module-level Map
• js-cache-storage - Cache localStorage/sessionStorage reads
• js-combine-iterations - Combine multiple filter/map into one loop
• js-length-check-first - Check array length before expensive comparison
• js-early-exit - Return early from functions
• js-hoist-regexp - Hoist RegExp creation outside loops
• js-min-max-loop - Use loop for min/max instead of sort
• js-set-map-lookups - Use Set/Map for O(1) lookups
• js-tosorted-immutable - Use toSorted() for immutability

8. Advanced Patterns (LOW)

• advanced-event-handler-refs - Store event handlers in refs
• advanced-use-latest - useLatest for stable callback refs

Instructions

Step 1: Classify the primary bottleneck before suggesting fixes

Start with references/perf-triage-modes.md and put the task into one dominant packet:

• waterfalls / async sequencing
• bundle weight / lazy loading
• RSC / server-client boundary mistakes
• rerender churn / memoization / context spread
• hydration or third-party script cost
• measurement-first unknowns

Step 2: Use the smallest support packet that answers the question

• references/perf-triage-modes.md — choose the main React / Next.js perf mode and first fixes
• references/measurement-and-tooling-checklist.md — decide what to measure with React Profiler, bundle analyzers, Web Vitals, or PR budget tooling
• references/boundaries-and-route-outs.md — keep the boundary with state-management, web-accessibility, responsive-design, and performance-optimization explicit
• AGENTS.md — deep rule catalog when a code generation or large refactor pass needs the full 45-rule reference

Step 3: Prefer measurement-led fixes over blanket cargo culting

Use the measurement checklist before recommending broad memoization or cache-heavy rewrites. React Compiler, bundle analyzers, and web vitals instrumentation have changed which old React performance heuristics are still worth applying blindly.

Step 4: Prioritize high-impact fixes first

1. Remove waterfalls and late-started async work. 2. Cut route JS and heavy client boundaries. 3. Fix hydration or script-placement mistakes. 4. Address rerender churn once the larger loading and boundary costs are understood.

Step 5: Route adjacent work out instead of absorbing everything

• App-wide state model choice → ../state-management/SKILL.md
• Accessibility-specific failures → ../web-accessibility/SKILL.md
• Layout adaptation / overflow / reflow work → ../responsive-design/SKILL.md
• Non-React or cross-stack bottlenecks → ../performance-optimization/SKILL.md

Examples

Promise.all for Independent Operations (CRITICAL)

// ❌ Sequential: 3 round trips
const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()

// ✅ Parallel: 1 round trip
const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

Avoid Barrel File Imports (CRITICAL)

// ❌ Imports entire library (200-800ms import cost)
import { Check, X, Menu } from 'lucide-react'

// ✅ Imports only what you need
import Check from 'lucide-react/dist/esm/icons/check'
import X from 'lucide-react/dist/esm/icons/x'

Dynamic Imports for Heavy Components (CRITICAL)

// ❌ Monaco bundles with main chunk ~300KB
import { MonacoEditor } from './monaco-editor'

// ✅ Monaco loads on demand
import dynamic from 'next/dynamic'
const MonacoEditor = dynamic(
  () => import('./monaco-editor').then(m => m.MonacoEditor),
  { ssr: false }
)

Use Functional setState (MEDIUM)

// ❌ Requires state as dependency, stale closure risk
const addItems = useCallback((newItems) => {
  setItems([...items, ...newItems])
}, [items])

// ✅ Stable callback, no stale closures
const addItems = useCallback((newItems) => {
  setItems(curr => [...curr, ...newItems])
}, [])

Best practices

1. Start with the lightest support packet that matches the problem; use AGENTS.md only when the smaller references are not enough. 2. Prefer evidence-led fixes: React Profiler, bundle analyzers, and Web Vitals should shape the recommendation before you prescribe memoization or caching. 3. Treat React Compiler as a live constraint on old memoization folklore; do not default to “wrap everything in memo”. 4. Keep React-specific advice separate from broader frontend concerns: use state-management for app-wide state choices, web-accessibility for WCAG remediation, and performance-optimization for non-React-wide bottlenecks. 5. Escalate to the compatibility alias vercel-react-best-practices only when an existing workflow explicitly requires that exact name. 6. Keep PR-budget and bundle-diff workflows in mind for real team usage; the skill should help with operational audits, not just code-level micro-fixes.

Constraints

Required Rules (MUST)

1. Eliminate waterfalls: Use Promise.all, Suspense 2. Bundle optimization: Prohibit barrel imports, use dynamic imports 3. RSC boundaries: Serialize only the data you need

Prohibited (MUST NOT)

1. Sequential await: Do not run independent fetches sequentially 2. Array mutations: Use toSorted() instead of sort() 3. Inline objects in React.cache: Causes cache misses

References

• references/perf-triage-modes.md
• references/measurement-and-tooling-checklist.md
• references/boundaries-and-route-outs.md
• AGENTS.md
• React Documentation
• Next.js Documentation
• SWR
• better-all
• Vercel Blog: Optimizing Package Imports
• Vercel Blog: Dashboard Performance

Metadata

Version

• Current version: 1.1.0
• Last updated: 2026-04-16
• Supported platforms: Claude, ChatGPT, Gemini
• Source: vercel/agent-skills

Related Skills

• performance-optimization: General performance optimization
• state-management: State management

Tags

#React #Next.js #performance #optimization #vercel #waterfalls #bundle-size #RSC #frontend

Boundaries and route-outs

Use this note to keep react-best-practices sharp instead of letting it absorb all frontend or performance work.

This skill owns

• React / Next.js performance triage for waterfalls, bundle weight, server-client boundaries, hydration/script cost, and rerender churn
• measurement-first audits of slow routes, heavy client components, and App Router performance regressions
• code-level React / Next.js performance refactors once the dominant bottleneck is clear

Route out to nearby skills

state-management

Use when the main problem is choosing where state should live or which store/query layer should own the data flow.

Examples:

• Context vs Zustand vs Redux Toolkit vs TanStack Query
• URL/form/local/shared/server-state ownership
• architectural state boundaries before performance tuning

web-accessibility

Use when the visible issue is keyboard/focus/semantics/aria/accessibility compliance.

Examples:

• focus traps, missing labels, screen-reader flow
• interactive semantics broken after a UI refactor
• accessibility verification is the primary ask

responsive-design

Use when the core task is layout adaptation, overflow, reflow, breakpoint/container logic, or mobile-first rendering behavior.

Examples:

• cards overflow on tablet
• layout collapses on small screens
• issue is primarily responsive adaptation, not route JS cost

performance-optimization

Use when the bottleneck is broader than React or spans backend, database, capacity, network, worker, or mixed runtime concerns.

Examples:

• slow API/database dominates the route
• memory, CPU, queue, or infra bottlenecks
• performance packet needs cross-stack tuning rather than React-specific guidance

Alias boundary

vercel-react-best-practices is a compatibility alias only. Use it when exact-name legacy tooling or user wording requires the old name. Ordinary React / Next.js performance requests should activate react-best-practices directly.

Practical rule

If you cannot name a specifically React / Next.js performance symptom, you probably need a different anchor first.

Measurement and tooling checklist

Use this file when the bottleneck is unclear or when you need evidence before recommending a refactor.

1. Choose the measurement surface

React subtree cost

Use when the complaint is rerender churn, expensive state updates, or interaction lag inside a known subtree.

• React DevTools Profiler / <Profiler>
• focus on which interactions are slow and which subtree re-renders repeatedly
• remember large apps can make profiling brittle; if the profiler freezes, fall back to broader browser traces

Source: <https://react.dev/reference/react/Profiler>

Route JS / dependency weight

Use when the page ships too much JavaScript or heavy components load on first render.

• Next bundle analyzer or equivalent bundle diff tooling
• compare before/after route weight and lazy-loaded splits
• if the team works through PRs, favor diff/budget tooling instead of one-off local screenshots

Sources:

• <https://nextjs.org/docs/14/pages/building-your-application/optimizing/bundle-analyzer>
• <https://github.com/hashicorp/nextjs-bundle-analysis>
• <https://nextjs.org/docs/app/guides/package-bundling>

User-facing page quality

Use when the symptom is poor LCP, CLS, INP, or a release readiness question.

• Core Web Vitals / field-vs-lab checks
• Next analytics or useReportWebVitals
• Speed Insights or another RUM surface when available

Sources:

• <https://web.dev/articles/vitals>
• <https://nextjs.org/docs/app/guides/analytics>
• <https://vercel.com/docs/speed-insights>

Hydration / script placement issues

Use when the issue is mismatch warnings, flicker, or degraded interaction after third-party scripts load.

• inspect script placement and loading strategy
• verify whether the problem is hydration, script cost, or a broader client-boundary mistake

Source: <https://nextjs.org/docs/app/guides/scripts>

2. Ask the minimum evidence questions

• Which route or interaction is slow?
• Is the complaint initial load, interaction lag, or dev-loop slowness?
• Do we already have profiler, CWV, or bundle evidence?
• Did the regression start after a routing, data-fetching, or third-party script change?

3. Pick the first tool, not every tool

• unknown symptom → CWV/Lighthouse or route-level reproduction first
• known large bundle → bundle analyzer first
• rerender suspicion → React Profiler first
• hydration/script warning → script and client-boundary review first
• mixed or inconclusive signal → browser performance trace after the first pass

4. Common real-world workflow

1. detect regression with CWV, Lighthouse, or user report 2. localize with React Profiler, bundle analyzer, or browser trace 3. classify into the triage modes 4. recommend the smallest high-impact fix first 5. re-measure after the fix instead of stacking speculative optimizations

5. Pitfalls

• Do not default to memo / useCallback before measuring.
• Do not treat all slow routes as bundle problems; waterfalls and boundary mistakes often dominate.
• Do not trust a single profiler screenshot as complete truth on very large pages.
• Do not keep React-specific work when the real issue is accessibility, layout, API latency, or database/runtime pressure.

React / Next.js performance triage modes

Use this file to classify the request before you touch AGENTS.md.

1. Waterfalls / async sequencing

Use when the page waits on independent fetches, late-started async work, or nested Suspense boundaries that serialize unnecessarily.

Signals

• “slow because it waits on three API calls”
• server components or loaders start work too late
• route HTML or data is delayed by sequential awaits

First fixes

• start independent work early
• use Promise.all for truly independent fetches
• move awaited work closer to the branch that needs it
• use Suspense for streaming instead of blocking the whole route

Primary references

• AGENTS.md waterfall rules
• <https://nextjs.org/docs/app/guides/lazy-loading>

2. Bundle weight / lazy loading

Use when too much JavaScript ships to the route, heavy components load eagerly, or third-party packages dominate the bundle.

Signals

• “bundle bloat”, “too much JS”, “dashboard route is huge”
• heavy editors/charts/modals loaded on first paint
• barrel imports or oversized icon/component packages

First fixes

• dynamic import heavy client components
• remove barrel imports and import narrower entry points
• defer third-party code until interaction or post-hydration
• re-check route JS with bundle analysis before and after

Primary references

• <https://nextjs.org/docs/app/guides/lazy-loading>
• <https://nextjs.org/docs/app/guides/package-bundling>
• <https://vercel.com/blog/how-we-optimized-package-imports-in-next-js>

3. RSC / server-client boundary mistakes

Use when the app pushes too much work to Client Components, serializes too much data, or confuses server-owned and client-owned logic.

Signals

• “client component too heavy”
• App Router route regressed after moving logic across the boundary
• lots of props or fetched data shipped only to support tiny client interactivity

First fixes

• move static / data-heavy work back to the server when possible
• minimize serialized props crossing the boundary
• isolate client-only instrumentation or interactivity into narrow islands
• avoid widening the client tree for analytics or convenience hooks

Primary references

• AGENTS.md server rules
• <https://nextjs.org/docs/app/api-reference/functions/use-report-web-vitals>
• <https://nextjs.org/docs/app/guides/analytics>

4. Rerender churn / memoization

Use when UI interactions feel sluggish because components, contexts, or callbacks trigger repeated render work.

Signals

• “rerenders too much”
• expensive child trees update when unrelated state changes
• context updates fan out across large subtrees

First fixes

• measure with React Profiler first
• reduce context spread and unnecessary parent updates
• use stable callback / memo patterns only where measurements justify them
• keep React Compiler in mind before prescribing blanket memo / useCallback

Primary references

• <https://react.dev/reference/react/Profiler>
• <https://react.dev/reference/react/memo>
• <https://react.dev/reference/react/useCallback>
• <https://react.dev/learn/react-compiler>

5. Hydration / script cost / third-party side effects

Use when the page flashes, mismatches, or slows down because browser-only code, analytics, chat widgets, or script injection happen at the wrong time.

Signals

• hydration mismatch warnings
• slow interaction after third-party scripts load
• layout shifts or client-only values cause flicker

First fixes

• isolate browser-only logic carefully
• move or defer scripts with Next script guidance
• separate user-visible hydration problems from broader state or accessibility issues
• verify whether the real issue is third-party script cost, not React rerenders

Primary references

• <https://nextjs.org/docs/app/guides/scripts>
• <https://nextjs.org/docs/app/guides/analytics>

6. Measurement-first unknowns

Use when the request only says “the page is slow” or “this route feels bad” and the bottleneck is not obvious.

Default workflow 1. collect the visible symptom and route scope 2. choose one measurement surface from measurement-and-tooling-checklist.md 3. classify into one dominant packet above 4. only then recommend specific fixes

Route-outs

• app-wide client/server state ownership → ../state-management/SKILL.md
• accessibility-specific failures → ../web-accessibility/SKILL.md
• layout adaptation / overflow / reflow → ../responsive-design/SKILL.md
• non-React-wide bottleneck or mixed backend/db/runtime issue → ../performance-optimization/SKILL.md