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

Stale data in preview or production

Likely causes:

• Cache expectation was never made explicit
• Revalidation settings do not match freshness needs
• Route became static or dynamic unintentionally
• Operator expects deploy-time behavior to invalidate runtime caches automatically

Checks:

• Write down the required freshness window
• Review fetch caching behavior and route-level rendering assumptions
• Check whether the route should be static, revalidated, or dynamic
• Confirm how invalidation or refresh is expected to happen operationally

Safe remediations:

• Align route or fetch behavior with the intended freshness model
• Prefer the smallest change that corrects freshness without making the whole route unnecessarily dynamic
• Add handoff notes describing how to verify the fix after deploy

Hydration mismatch after refactor

Likely causes:

• Browser-only APIs used during server render
• Non-deterministic values like time, random output, or locale-sensitive formatting without coordination
• Different markup paths on server and client

Checks:

• Search for window, document, storage APIs, or time-based rendering in shared components
• Compare server and client branches for divergent markup
• Check whether a component should be isolated behind a client boundary instead of partially executing on both sides

Safe remediations:

• Move browser-only logic into client components or effects where appropriate
• Make initial render deterministic
• Keep server markup and client hydration paths aligned

High re-render count or sluggish interaction

Likely causes:

• State lifted too high
• Broad context updates
• Expensive child tree under frequently changing props
• Memoization added without addressing prop instability

Checks:

• Identify the smallest subtree that actually depends on the changing state
• Review whether a provider wraps too much of the tree
• Look for unstable object or function props passed into expensive children
• Confirm that the expensive work is real before adding memoization

Safe remediations:

• Move state closer to where it is used
• Split expensive children from frequently updated parents
• Narrow context scope
• Add memoization only after structural fixes or measured need

Bundle regression after adding a feature

Likely causes:

• Heavy client-only dependency imported at route root or shared layout
• Entire route tree converted to use client
• Optional widgets loaded eagerly

Checks:

• Review recent imports in layouts, route entries, and shared providers
• Identify feature code that could be deferred or isolated
• Check whether the dependency is needed during first render

Safe remediations:

• Push the dependency deeper into a smaller client island
• Lazy-load optional or below-the-fold widgets
• Keep the route shell server-rendered where possible

CLS or visual instability

Likely causes:

• Images without stable dimensions
• Font swaps or too many font variants
• Late-loading embeds or scripts changing layout

Checks:

• Confirm image sizing strategy
• Check font loading path and variant count
• Review late DOM injection from third-party code

Safe remediations:

• Provide stable image dimensions or fill containers correctly
• Use next/font and reduce variants
• Reserve space for embeds where practical

Examples

Example 1: Review an App Router product route with poor LCP

Use examples/performance-review-runbook.md, scenario 1.

Expected pattern:

• confirm route is App Router
• inspect whether app/products/[id]/page.* or shared layout became client-heavy
• verify hero image handling and third-party script timing
• narrow changes to the route and record measurable validation criteria

Example 2: Investigate stale dashboard data after deploy

Use examples/performance-review-runbook.md, scenario 2.

Expected pattern:

• document freshness expectation first
• inspect cache and rendering assumptions
• avoid turning the whole route dynamic unless required
• add post-deploy verification and rollback notes

Additional Resources

• references/nextjs-performance-guardrails.md — compact operator matrix for routing mode, cache intent, optimization primitives, and Core Web Vitals interpretation.
• Official references to consult when needed:
  • Next.js documentation
  • React documentation
  • Vercel Speed Insights
  • Vercel Analytics
  • web.dev Core Web Vitals guidance

Related Skills

Hand off when the primary task becomes:

• accessibility auditing rather than performance analysis
• test strategy or test automation design
• security review of browser code or third-party dependencies
• deployment platform configuration outside the frontend performance path
• visual design or styling with no rendering, loading, or cache concern

Provenance Note

This skill preserves the identity and intent of the upstream community skill while improving its execution quality for operators. Keep provenance explicit in review notes when using imported upstream material or adapting rule guidance into repository-specific remediation.