React Best Practices V2

Vercel React Best Practices

Overview

This skill curates the upstream react-best-practices workflow into an operator-ready execution path for React and Next.js performance work.

Keep the original intent: improve performance without cargo-cult optimizations, preserve provenance, and stay aligned with modern React and Next.js guidance. The upgraded workflow adds sharper activation boundaries, App Router vs Pages Router decision points, measurable validation, and compact local support files that help operators inspect a repository and document safe remediation.

Use this skill for performance-sensitive work in React or Next.js when the task involves one or more of these concerns:

• route or component slowness
• excessive client-side JavaScript
• cache or revalidation confusion
• hydration mismatch risk
• image, font, or third-party script regressions
• code review of React or Next.js performance changes
• performance validation before deploy or handoff

Ask one clarifying question before changing code if any of these are unclear:

• Is this App Router or Pages Router?
• Is the problem seen locally, in preview, or in production?
• Is the target symptom slow initial load, slow navigation, stale data, hydration mismatch, or poor Core Web Vitals?

When to Use This Skill

Activate this skill when the request is primarily about React or Next.js performance behavior, rendering strategy, loading behavior, or cache-aware delivery.

Good fit

• Writing or refactoring Next.js pages, layouts, or route segments with performance goals
• Reviewing use client boundaries or deciding what should stay server-side
• Fixing slow LCP, CLS, INP, hydration mismatch, or bundle growth
• Reviewing image, font, script, or lazy-loading decisions
• Investigating stale data caused by caching or revalidation assumptions
• Preparing a performance-focused PR review, deployment review, or handoff note

Usually not the right skill

• Pure styling or design-system work with no performance concern
• Accessibility audits as the main objective
• Security reviews unrelated to frontend performance behavior
• CI/CD pipeline design unrelated to frontend build or deploy verification
• Generic React bugs with no rendering, loading, or cache dimension

If the request drifts into testing strategy, accessibility, security hardening, or deployment platform design, hand off to a more specific skill after capturing any performance findings already confirmed.

Operating Table

Workflow

1. Confirm the target symptom and success metric.

   • Examples: better LCP on /products/[id], lower client JS on the home route, reduced CLS from font swaps, correct freshness for dashboard data.
   • Do not start with blanket memoization or lazy loading.

2. Identify execution context.

   • Determine whether the codebase uses App Router, Pages Router, or both.
   • Confirm whether the environment is local, preview, or production.
   • Record whether the issue is route-specific, component-specific, or global.

3. Capture the intended rendering and freshness model before editing.

   • For App Router, decide whether the target should be static, revalidated, or fully dynamic.
   • For Pages Router, confirm whether the route uses static generation, server-side rendering, or client fetching.
   • Write down the expected freshness window and invalidation path.

4. Run the read-only inspection first.

   • Use:

     bash scripts/inspect-nextjs-performance.sh .

   • Treat the output as triage, not proof. Confirm each finding manually in code.

5. Review architecture before micro-optimizing.

   • In App Router, prefer Server Components by default.
   • Add use client only where interactivity, browser APIs, or client-only hooks are required.
   • Split large client trees into a server shell plus small client islands when possible.
   • Move data fetching out of client effects when framework-native server loading is available.

6. Check first-party optimization primitives.

   • Images: prefer next/image, correct sizing, and careful priority usage.
   • Fonts: prefer next/font; reduce unnecessary variants.
   • Scripts: justify each third-party script and use the least aggressive loading strategy that works.
   • Lazy loading: use for heavy optional client code, not as a substitute for bad architecture.

7. Only then consider React-specific render tuning.

   • Investigate state placement, prop churn, broad context updates, and expensive child trees first.
   • Use memo or useMemo only when measurement or code structure shows a real payoff.
   • Do not wrap nearly everything in memoization as a default response.

8. Validate safely.

   • Prefer narrow, reversible changes.
   • Rebuild and rerun the relevant local checks.
   • Compare route behavior before and after.
   • For production-sensitive work, define what must be verified in preview or production metrics.

9. Document deploy and rollback notes.

   • Record what changed, why the chosen rendering/cache mode is correct, and what symptom should improve.
   • If a change touches caching, note how to verify stale-content recovery and what fallback action to take if freshness becomes wrong after deploy.

Troubleshooting

Slow initial render or poor LCP

Likely causes:

• Large client component boundary near the route root
• Heavy imports in app/layout.*, route entry files, or shared providers
• Unoptimized hero image or incorrectly prioritized assets
• Early third-party script execution

Checks:

• Search for broad use client usage in layouts, templates, and top-level pages
• Check whether the LCP image uses next/image with correct sizing
• Check whether fonts are loaded through next/font
• Review third-party scripts and whether they load before interaction

Safe remediations:

• Move non-interactive UI back to server-rendered components
• Split heavy widgets behind client islands or lazy loading
• Replace plain <img> with next/image where appropriate
• Delay or remove non-essential third-party scripts