Org Skills

react-performance

Diagnose and fix React web performance problems by measuring first — slow renders and re-render storms, poor Core Web Vitals (LCP, INP, CLS), slow TTFB on Next.js 16, large bundles, janky long lists and memory leaks — using React Performance Tracks, the React DevTools Profiler, web-vitals attribution, React Compiler bail-out lints, virtualisation, Activity, transitions and 'use cache'.

Download .zip Raw Source
When agents use itUse this whenever the user says a React or Next.js app is slow, laggy, janky, "re-rendering too much", has a bad Lighthouse or PageSpeed score, high INP or LCP, slow TTFB, a bundle that is too big, a typing or scrolling lag, growing memory, or asks whether to add useMemo, useCallback or React.memo, how to virtualise a table, or how to read the Profiler. Also use it when a slow page turns out to be a data waterfall or caching problem rather than rendering. For React Native use react-native-performance.

Install

Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.

npx skills add AGCO-Global/org-skills --skill react-performance -a github-copilot
# or with the org installer (adds .github/skills/react-performance):
npx -y github:AGCO-Global/org-skills add skill react-performance

Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.

npx skills add AGCO-Global/org-skills --skill react-performance
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill react-performance -g

Installs the frontend-react-skills plugin, which bundles all Frontend / React skills and keeps them updated.

/plugin marketplace add AGCO-Global/org-skills
/plugin install frontend-react-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill react-performance -a claude-code

Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.

Installs into .agents/skills/, which Codex reads.

npx skills add AGCO-Global/org-skills --skill react-performance -a codex

Installs into Cursor's skills folder.

npx skills add AGCO-Global/org-skills --skill react-performance -a cursor

Installs into Gemini CLI's skills folder.

npx skills add AGCO-Global/org-skills --skill react-performance -a gemini-cli

Nothing to install. Press Download .zip above, unzip it, and drop the react-performance folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.

The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.

Skill contents

React Performance

Targets: React 19.2 · React Compiler 1.0 · Next.js 16 · web-vitals 5 · Verified: 2026-09 against https://react.dev/blog/2025/10/01/react-19-2 , https://react.dev/learn/react-compiler , https://nextjs.org/docs , https://web.dev/articles/vitals

Performance work is a measurement, then the smallest change that moves that number, then the same measurement again. Never answer "it is slow" with a list of tips: get the metric, the device and the interaction first. Web only — for React Native or Expo use react-native-performance.

1. Decide first

Question Default Change when
Which metric is the problem? Ask for or record one number: LCP, INP, CLS, TTFB, commit duration, JS bytes, heap growth The user cannot measure → give the exact recording steps (§2) before any fix
Where to measure? Production build, mid-range phone or 4× CPU throttle, field data (web-vitals) over lab data Pure regression hunt between two commits → lab (Lighthouse CI) is enough
Memoise by hand? No. React Compiler on; fix what its lint reports The Profiler shows an expensive commit and the lint shows the component is not compiled or the value crosses into a non-compiled library
Long list Paginate on the server; virtualise above ~100 rendered rows with @tanstack/react-virtual Rows need find-in-page or print → paginate instead; content-visibility: auto for medium lists
Typing or filtering lag useDeferredValue on the derived view; input state stays urgent Work is CPU-bound beyond ~50 ms even once → Web Worker
Hidden tabs, drawers, back-navigation Unmount Re-mounting is the slow part or state must survive → <Activity mode="hidden"> (React 19.2)
Next.js slow TTFB Parallel data + <Suspense> streaming + 'use cache' (Cache Components) Personalised per request → stream it in a Suspense hole; never make the whole route dynamic-blocking

2. Measure: symptom → tool → number

Symptom Tool Capture
Slow load Lighthouse / PageSpeed Insights (field data tab), WebPageTest LCP and its element, TTFB, JS transferred
Laggy interaction Chrome Performance panel with React Performance Tracks (19.2: Scheduler and Components tracks), web-vitals/attribution onINP INP, the target element, input delay vs processing vs presentation
"Re-renders too much" React DevTools Profiler with "Record why each component rendered" Commits per interaction, slowest commit, why it rendered
Not memoised though the compiler is on eslint-plugin-react-hooks recommended-latest (compiler rules) The line that made the compiler skip the component
Layout jumps Performance panel → Layout Shifts track CLS and the shifting node
Memory grows DevTools Memory: heap snapshot, navigate away and back 5×, snapshot, compare Detached nodes, listeners, retained size
Bundle too big @next/bundle-analyzer, vite-bundle-visualizer, source-map-explorer Largest chunks, duplicates, what pulled them in

Write the baseline down with device, network and build. Recording steps and the INP attribution snippet: references/measurement.md.

3. Rendering: work through in this order

  1. Is it actually expensive? A 0.3 ms component rendering 50 times is fine. Only fix commits the Profiler or the Components track shows as long.
  2. Compiler first. React Compiler 1.0 works on React 17+ (target option plus react-compiler-runtime below 19). Turn it on, run the lint, fix the purity violations it reports (mutation in render, ref.current read in render, conditional hooks). That removes most prop-identity re-renders without memo.
  3. Move state down / lift content up. State used by one child moves into it; expensive static subtrees are passed as children so they keep their element identity.
  4. Split or replace context. One context with 15 values re-renders every consumer; split by change frequency or move to a selector store (Zustand, Jotai).
  5. Manual memo/useMemo/useCallback last, only where step 2 cannot apply: values handed to non-compiled third-party components, or libraries flagged by the react-hooks/incompatible-library rule (the compiler skips those components).
  6. Urgent vs non-urgent. startTransition for state that can lag (results, charts); useDeferredValue(query) for a derived view; the text input itself is never deferred or debounced.

4. Lists, interaction and memory

  • Virtualise with useVirtualizer (count, getScrollElement, estimateSize, overscan); fixed row height is far cheaper than measured. Keys from ids. react-window only as v2 (List with rowComponent) — v1 FixedSizeList samples no longer compile. Sample: references/fixes.md.
  • Do not fetch 10 000 rows to virtualise them: paginate or cursor-scroll on the server, filter and sort there too.
  • Keep handlers under ~50 ms. Break up long tasks with await scheduler.yield() (feature-detect; fall back to setTimeout(…, 0)); move parsing, search indexing and diffing to a Web Worker.
  • Debounce network calls, not the UI echo. Batch DOM reads before writes; content-visibility: auto with contain-intrinsic-size on long off-screen sections.
  • Leaks: every addEventListener, setInterval, socket, observer and store subscription returns a cleanup; no DOM nodes or large arrays in module scope; bounded gcTime for huge rarely revisited queries.

5. Loading: bundle, images, fonts, third parties

  • Every route is its own chunk (automatic in Next.js and React Router framework mode; lazy route objects in data mode). lazy() + <Suspense> for heavy widgets (charts, editors, maps) and anything below the fold.
  • Audit imports: whole-library imports (lodash, icon packs, moment) → per-function imports, Intl.*, date-fns. One React copy in a monorepo. Keep 'use client' at leaves — a boundary ships its whole import graph.
  • LCP image: real <img>/next/image with width/height, sizes, AVIF/WebP, fetchPriority="high" or loading="eager" (in next/image 16 the priority prop is deprecated; preload replaces it), never lazy. Everything else loading="lazy" decoding="async".
  • Fonts: self-host, subset, font-display: swap or optional, preload the one critical file (preload() from react-dom).
  • Third-party scripts: next/script strategy="lazyOnload" or load on interaction; profile their long tasks separately — they are often the entire INP problem.
  • Guard it: size-limit or Lighthouse CI budgets in the pipeline so the number cannot silently regress.

6. Server and data (Next.js 16, React Router v8)

  • Kill waterfalls: start independent requests together (Promise.all), load in the Server Component or loader, never mount-then-fetch.
  • Stream: static shell first, slow or personalised parts inside <Suspense>; with cacheComponents: true the shell is prerendered (PPR) and the holes stream — there is no page-level static/dynamic switch any more.
  • Cache explicitly: 'use cache' + cacheLife('hours') + cacheTag(…) on the data function; invalidate with updateTag (Server Actions) or revalidateTag(tag, 'max'). unstable_cache and fetch(…, { next: { revalidate } }) are the pre-16 APIs — migrate them. Details: nextjs-16.md in ../react-architecture/references/.
  • React Router: parallel loaders per matched route already run together; add Cache-Control via the headers export and prefetch with <Link prefetch="intent">.

7. Deliverable format

## Baseline
<metric>: <value> — tool, build (prod), device/throttle, network, interaction measured

## Findings (by impact)
1. <problem> — evidence (profile track, lint output, bundle treemap, waterfall) — expected gain

## Fixes
Per finding: the minimal diff, why it moves the metric, risk

## Verify
Same measurement, same conditions: before → after. Budget or CI check added: <which>

Checklist

  • A baseline number exists with tool, device and build recorded
  • Measured on a production build, not the dev server (StrictMode double render, no minification)
  • Compiler lint output checked before any manual memoisation was added
  • No useMemo/useCallback/memo added without Profiler evidence
  • Input stays urgent; derived or heavy updates use useDeferredValue/startTransition
  • Lists over ~100 rendered rows are paginated or virtualised; keys are ids
  • LCP element identified; it is not lazy-loaded and has dimensions
  • Next.js caching is explicit ('use cache', cacheLife, tags); no unstable_cache in new code
  • Effects with subscriptions return cleanups; heap compared across navigations when memory was the complaint
  • The same metric was re-measured and a budget guards it in CI

Anti-patterns

  • Optimising without a baseline ("it's obviously the list") → record the metric, then change one thing.
  • memo/useMemo everywhere by policy → compiler on, lint clean, memo only where evidence says so.
  • Profiling the dev server → next build && next start / vite build && vite preview.
  • Debouncing the input's own state → keep the echo instant; defer the derived view, debounce the request.
  • Virtualising 10 000 client-side rows → server pagination first.
  • Making a whole Next.js route dynamic because one widget is personalised → static shell + Suspense hole.
  • unstable_cache / one-argument revalidateTag in Next.js 16 code → 'use cache', revalidateTag(tag, 'max'), updateTag.
  • Shared React anti-patterns (effect-fetch, derived state, index keys): react-anti-patterns.md in ../react-development/references/.

Go deeper

  • references/measurement.md — recording a trace with React Performance Tracks, Profiler workflow, web-vitals INP attribution code, heap-snapshot procedure, bundle analysis commands, CI budgets.
  • references/fixes.md — virtualised list, useDeferredValue filter, <Activity> tabs, scheduler.yield() chunking, Web Worker hand-off, resource hints, compiler configuration per bundler.
  • nextjs-16.md in ../react-architecture/references/ — Cache Components, 'use cache', invalidation APIs.
  • Sibling skills: react-development (writing the component), react-architecture (framework and state choices), react-testing, frontend-code-review (reviews), react-native-performance (mobile).

References

Deeper material the agent loads only when needed.