React Performance Pass

---
name: react-performance-pass
description: Reviews a React or Next.js codebase for performance in bottleneck order - request waterfalls first, then work that blocks the main thread, then wasted re-renders, then bundle and asset weight - and returns findings ranked by how many milliseconds each one actually costs. Use when a page feels slow, when typing or scrolling stutters, or before shipping a performance-sensitive route.
---

# React Performance Pass

You are the reviewer who refuses to memoise anything until the waterfall is gone. Effort goes where the milliseconds are, and the ordering of the findings is most of the value.

## Workflow

1. **Ask what "slow" means.** Slow to appear, slow to respond, or slow to scroll. These have three different causes and almost no overlap.
2. **Establish the setup.** App Router, Pages Router, or a client-only SPA. Which components are server components. Where data is fetched.
3. **Get or take a measurement.** A network trace, a React Profiler recording, or a Lighthouse run. Without one you are guessing, and guesses default to memoisation.
4. **Walk the bottleneck ladder in order** (below). Stop descending once you have found something that plausibly accounts for the reported delay.
5. **Rank findings by cost**, with the evidence next to each.
6. **Fix one thing, re-measure.** Stacked changes hide which one worked.

```text
Performance pass checklist
[ ] Symptom classified: slow load / slow input / slow scroll
[ ] Router model and server-vs-client boundary understood
[ ] A real measurement in hand before any code changes
[ ] Data fetching checked for sequential awaits
[ ] Main-thread work checked before re-renders
[ ] Re-render causes traced to a source, not assumed
[ ] Bundle checked with an analyser, not by eye
[ ] Findings ordered by measured cost, each with a fix
[ ] One change made, then re-measured
```

## The bottleneck ladder

### 1. Request waterfalls - usually the biggest win

Sequential awaits, or a component that fetches after its parent has already fetched. Each hop costs a full round-trip before anything renders.

Look for: `await` on one line, another `await` using the first result on the next; a child component with its own `useEffect` fetch; a layout that fetches, then a page that fetches.

Fix: run independent requests with `Promise.all`. Move fetching to the server component or route loader. Where a genuine dependency exists, start the independent half immediately and await both at the end. Stream what you can render early.

One waterfall fix routinely beats every render optimisation in the file combined. Say so in the report.

### 2. Client fetching that should be server-side

Data fetched in a `useEffect` after hydration costs the user a second round-trip they can see. If the server could have fetched it at request time, it should have.

Fix: move the fetch into a server component, or a loader, and keep client components for interactivity. Watch for the opposite bug too: a page rendered on the server that refetches the same data on the client anyway.

### 3. Main-thread work

Before blaming re-render counts, check what each render *does*. Sorting 10,000 rows, parsing dates, running a syntax highlighter, or building a large derived object on every keystroke will stutter at any render count.

Fix: memoise the computation with `useMemo`, move it out of render, do it once at the data layer, or push it to a worker. Virtualise long lists rather than rendering thousands of nodes.

### 4. Wasted re-renders

Now look at what renders and why. The React Profiler names the trigger; use it rather than guessing.

Common causes, in the order they are usually the answer:

- State living too high, so a keystroke re-renders a page.
- A context whose value is a new object every render, waking every consumer.
- New object, array, or function props created inline, breaking every child's identity check.
- A parent re-rendering for an unrelated reason and dragging expensive children with it.

Fix in the same order: move state down or colocate it, split the context, stabilise the value, and only then reach for `memo`, `useMemo` or `useCallback`. Memoisation is the last step because it hides the cause rather than removing it, and it has its own cost.

### 5. Bundle and hydration weight

Measure with the bundle analyser before touching anything. Look for one dependency dominating the client bundle - a chart library, a date library, an editor, an icon set imported wholesale.

Fix: dynamic-import heavy client-only widgets, keep components on the server where possible, import single icons rather than the barrel file, replace a large utility library with a smaller one or a few lines of your own.

### 6. Images, fonts and layout shift

Right-size and lazy-load images, use the framework's image primitive, always set dimensions, subset fonts and set `font-display`. These rarely cause the complaint but they are cheap and they move the visible metrics.

## Output format

Ordered by impact, highest first. Each finding:

- **Impact** - High / Medium / Low, with the cost in milliseconds or kilobytes where you have it.
- **Where** - file and symbol.
- **Problem** - the specific pattern, in one or two sentences.
- **Fix** - the change, with a short before-and-after where it clarifies.
- **Confidence** - measured, or inferred from reading the code.

A flat unordered list wastes the reader's time. If two findings are close, say which to do first and why.

## Example

**High impact - `app/dashboard/page.tsx`, measured 1.9s to first byte.**

Problem: three sequential awaits before anything renders.

```ts
const user = await getUser();                 // 180ms
const team = await getTeam(user.teamId);      // 210ms
const projects = await getProjects(team.id);  // 240ms  -> 630ms serial
```

Fix: `getTeam` and `getProjects` both depend on `user`, but not on each other. Once the user is loaded they can run together.

```ts
const user = await getUser();                                    // 180ms
const [team, projects] = await Promise.all([                     // 240ms
  getTeam(user.teamId),
  getProjectsByTeamId(user.teamId),
]);
```

Saves roughly 210ms on every dashboard load. `getProjectsByTeamId` already exists in `lib/projects.ts`; the original chain was passing `team.id`, which equals `user.teamId`, so no new query is needed.

**Confidence:** measured, server timing headers on ten loads.

## Common false wins

- Wrapping everything in `memo` while a three-request waterfall upstream costs 600ms.
- Adding `useCallback` to a prop that was never the reason a child re-rendered.
- Debouncing an input to hide a re-render storm instead of moving the state down.
- Code-splitting a 4KB component while a 300KB dependency still ships on every page.
- Rendering a 5,000-row list unvirtualised and blaming React for the scroll jank.
- Server-rendering a page that refetches the same data on the client immediately after hydration.

Each of these is motion without movement. Confirm the bottleneck, then fix it.

## Rules

- Measure, or point to the evidence, before calling anything the bottleneck.
- Never lead with `memo`, `useMemo` or `useCallback`. They are the last step of stage 4, not the first thing you try.
- One change at a time, then re-measure. Two changes make the result unreadable.
- If a fix changes behaviour - stale data, different loading order, a lost error state - flag the trade-off rather than burying it.
- Do not report a finding you cannot tie to a file and a symbol.
- Say when a finding is inferred rather than measured. An honest "probably" beats a confident number you did not observe.

## Edge cases

- **No measurement available and none possible.** Review statically, order findings by how much they usually cost, and label the whole report as unmeasured.
- **The app is fast and the user is not.** Sometimes the slow part is the API, the database, or the network, not React. Say so and point at where the time goes rather than optimising the front end for a backend problem.
- **Slowness only in development.** Development builds re-render more, ship unminified code, and run extra checks. Reproduce against a production build before investigating.
- **A single user is slow.** Suspect their data volume, an extension, or an old device before changing code that is fine for everyone else.
- **The framework version matters.** Compiler-driven auto-memoisation and streaming behaviour differ between versions. Check what the project is on before recommending a pattern it does not support.
- **The real fix is architectural.** If the page needs a different data model, say that plainly and offer the cheap partial win separately, with its smaller number attached.

## Files

- `references/examples.md` - three full reviews with the code, the measurement, the fix and the result: a Next.js waterfall, a re-render storm traced to a context value, and a bundle dominated by one dependency. Read it for the shape of a finding and for how much evidence to attach.

# Worked performance reviews

Three reviews, each from the reported symptom through to the re-measurement. Note how much of each one is spent establishing the number before any code changes.

## Contents

- [Review 1: slow to appear - a waterfall in a Next.js route](#review-1-slow-to-appear---a-waterfall-in-a-nextjs-route)
- [Review 2: slow to respond - a context value woke the whole page](#review-2-slow-to-respond---a-context-value-woke-the-whole-page)
- [Review 3: slow on first visit - one dependency owned the bundle](#review-3-slow-on-first-visit---one-dependency-owned-the-bundle)
- [Patterns across the three](#patterns-across-the-three)

---

## Review 1: slow to appear - a waterfall in a Next.js route

### Symptom

"The reports page takes forever to load." Two to three seconds before anything appears, consistently, on a fast connection.

### Measurement first

Server timing on ten loads of `/reports`: median 2,180ms to first byte, 240ms to render after that. The delay is entirely server-side, so nothing in the component tree is worth reading yet.

### What the code did

```ts
// app/reports/page.tsx
export default async function ReportsPage() {
  const session = await getSession();                       // 120ms
  const org = await getOrg(session.orgId);                  // 260ms
  const members = await getMembers(org.id);                 // 310ms
  const reports = await getReports(org.id);                 // 890ms
  const settings = await getReportSettings(org.id);         // 180ms
  return <ReportsView org={org} members={members} reports={reports} settings={settings} />;
}
```

Five sequential round-trips, 1,760ms of which 1,640ms is spent waiting on requests that mostly do not depend on each other.

### The dependency graph, written out

- `getSession` - depends on nothing.
- `getOrg` - needs `session.orgId`.
- `getMembers`, `getReports`, `getReportSettings` - all need only `org.id`, which equals `session.orgId`.

So the real chain is two levels deep, not five.

### The fix

```ts
export default async function ReportsPage() {
  const session = await getSession();                       // 120ms
  const [org, members, reports, settings] = await Promise.all([
    getOrg(session.orgId),
    getMembers(session.orgId),
    getReports(session.orgId),
    getReportSettings(session.orgId),
  ]);                                                        // 890ms, the slowest one
  return <ReportsView org={org} members={members} reports={reports} settings={settings} />;
}
```

### Result

Time to first byte: 2,180ms to 1,040ms, median of ten loads. The page now costs what its slowest query costs.

### The second finding, reported but not done

`getReports` alone is 890ms. It is a full table scan filtered in application code. Fixing that is a backend change worth roughly another 700ms, and it is filed separately because it touches a different codebase and needs its own testing.

### What was deliberately not done

No memoisation, no component splitting, no virtualised table. The render was 240ms of a 2,180ms problem, so any work there would have been invisible to the user.

---

## Review 2: slow to respond - a context value woke the whole page

### Symptom

"Typing in the filter box lags." Characters appear roughly 200ms behind the keystroke on a list of 400 rows.

### Measurement first

React Profiler, recording six keystrokes: each keystroke commits 418 components, 180-240ms per commit. The offenders are 400 `<RowItem>` components plus a `<ChartPanel>` that is not related to filtering at all.

### What the code did

```tsx
function AppProviders({ children }) {
  const [filters, setFilters] = useState({ q: '', status: 'all' });
  const [user] = useUser();
  // new object identity on every render
  return (
    <AppContext.Provider value={{ filters, setFilters, user, theme: 'light' }}>
      {children}
    </AppContext.Provider>
  );
}
```

Every consumer of `AppContext` re-rendered on every keystroke, including components that only read `user`. The context value was rebuilt each render, so identity checks never helped.

### Fixes, in the order they were applied

**1. Move the state to where it is used.** The filter text only matters to the toolbar and the list. Moving `filters` out of the global provider into a `FilterProvider` wrapping just those two subtrees removed `<ChartPanel>` and 12 other components from the commit entirely.

**2. Split the remaining context.** `user` and `theme` change roughly never; `filters` changes per keystroke. Two providers, so a filter change cannot wake a `user` consumer.

```tsx
<UserContext.Provider value={userValue}>       {/* memoised, changes on login */}
  <FilterContext.Provider value={filterValue}> {/* changes per keystroke */}
```

**3. Only then, memoise.** `<RowItem>` was wrapped in `memo` and its `onSelect` prop stabilised with `useCallback`. This is step three because after steps one and two only the list still re-rendered, which is correct behaviour - the list is what the filter changes.

### Result

Per-keystroke commit: 418 components to 34, and 180-240ms to 11-16ms. Typing is immediate.

### The false win that was avoided

The first instinct was to debounce the input by 300ms. That would have made typing feel smooth while leaving 418 components re-rendering per debounced update, so the results list would have stuttered instead. Debouncing hides the symptom and keeps the cause.

---

## Review 3: slow on first visit - one dependency owned the bundle

### Symptom

"First load on mobile is bad." Lighthouse on a mid-tier phone profile: 4.6s to interactive, 812KB of JavaScript on the marketing home page.

### Measurement first

Bundle analyser output, largest client chunks:

```
charting library          318 KB   used on /analytics only
date utility (full)       74 KB    used for 3 format calls
icon set (barrel import)  61 KB    12 icons actually rendered
markdown renderer         52 KB    used on /docs only
application code          97 KB
```

453KB of the bundle belonged to three routes the visitor had not opened.

### The fixes

**1. Dynamic-import the chart.** It is client-only, below the fold, and irrelevant to every route except `/analytics`.

```ts
const RevenueChart = dynamic(() => import('@/components/RevenueChart'), {
  ssr: false,
  loading: () => <ChartSkeleton />,
});
```

318KB left the shared bundle and now loads only when someone opens the analytics page.

**2. Replace the date library.** Three calls, all formatting a timestamp as a short date. Replaced with `Intl.DateTimeFormat`, which is in the runtime. 74KB gone, four lines of application code added.

**3. Fix the icon import.** `import { Search, Menu } from 'icons'` pulled the whole set through the barrel file. Switching to per-icon paths dropped it to about 4KB.

**4. Route-split the markdown renderer.** Moved into the `/docs` route segment instead of the shared layout.

### Result

Home page JavaScript: 812KB to 148KB. Time to interactive on the same phone profile: 4.6s to 1.9s. The analytics page gained about 200ms on first open, which was accepted - far fewer people open it than open the home page.

### The trade-off, stated rather than hidden

The chart now flashes a skeleton on the analytics route. That is a real regression for analytics users and it was called out in the report so the team could decide, rather than being discovered later.

---

## Patterns across the three

1. Every review produced a number before it produced an opinion. Two of the three ended up somewhere the reader did not expect.
2. The symptom classified the search. "Slow to appear" led to the network, "slow to respond" led to the profiler, "slow on first visit" led to the bundle analyser. None of the three investigations would have found the others' bug.
3. Memoisation appeared once, as the third step of one review, after the structural fixes had already removed most of the work.
4. Each review names a finding it did not act on - a backend query, a route regression - rather than pretending the fix was free.
5. The result is always the same measurement repeated, not a claim that it should be faster now.