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'.
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.
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.
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/attributiononINP
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
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
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.
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.
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.
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).
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).
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/scriptstrategy="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.
---
name: react-performance
description: >
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'. Use 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.
metadata:
technology: React
type: performance
---
# 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).