React Performance

React Performance

Performance work fails in two predictable ways: optimizing something that was never the bottleneck, and buying speed with a mutation, a cast, or a deleted test. This skill exists to prevent both. It owns the method; the rule catalogues own the rules.

The catalogue is not the plan. Vercel's rules are ordered by typical impact, not by what is slow in this application. A rule earns its way into a diff by a measurement, not by appearing high in the list.

Where the Rules Live

Read the catalogue that matches the question before proposing a change:

If two catalogues disagree, the more specific one wins: Next-specific semantics over general React, field-metric guidance over component-level micro-cost.

The Method

1. Establish the baseline

Name the symptom in user-observable terms — a slow route, an unresponsive input, a heavy first load — and capture a number before touching code: a profile, a bundle report, a trace, a field metric. Record how it was measured so the same measurement can be repeated.

Complete when: the symptom, the measurement method, and the starting number are all written down, and the number is reproducible.

2. Locate the cost

Find where the time actually goes before choosing a category. The prioritized order in the catalogue is a good search order — waterfalls and bundle size first, js- micro-optimizations last — but it is a hypothesis generator, not a diagnosis. React Profiler, next build output, a bundle analyzer, and a network waterfall are evidence; a plausible story about re-renders is not.

Complete when: the dominant cost is attributed to a specific boundary — a request waterfall, a bundle entry, a serialization payload, a re-render path, a layout or hydration step — with the evidence that attributes it.

3. Apply one rule at a time

Read the specific rule file, then change one thing. Batched "performance passes" make the re-measurement uninterpretable and turn a review into a guess.

Before the change lands, check it against the house rules below.

Complete when: exactly one hypothesis is in the diff, and the rule it implements is named.

4. Re-measure and keep the evidence

Repeat the step-1 measurement. A change that does not move the number is reverted, not kept "because it is better practice" — an unmeasured optimization is mechanism without benefit, and reduce-system-complexity treats added mechanism as a cost.

Record the before/after pair in the PR. Performance is a non-functional guarantee, so this measurement is the evidence for the change; it does not substitute for the behavior tests, which must be unchanged and green.

Complete when: the same measurement is reported before and after, and every behavior test still passes without modification.

Where House Rules Win

Performance advice written for the general case sometimes trades away something this repository does not trade. When they collide, these hold:

1. Behavior tests do not change to accommodate a performance change. A perf refactor that requires editing assertions is a behavior change wearing a disguise — route it through tdd. Deleting or weakening a test to make a benchmark look better is never in scope.
2. Immutability holds until a measurement says otherwise. js- rules that cache property lookups, mutate accumulators, or reuse arrays in hot loops are legitimate inside a proven hot path, and only there. The mutation stays local to a pure function's own scope — never a caller's array or a shared object. See functional.
3. No any, no unjustified assertion, for speed. Skipping schema validation at a trust boundary is a correctness change, not an optimization. See typescript-strict.
4. Memoization is earned, not default. rerender- rules assume a measured re-render problem. rerender-simple-expression-in-memo is in the catalogue precisely because reflexive useMemo/memo costs more than it saves. Prefer deleting the cause — derived state during render, a narrower subscription, a moved boundary — over adding a cache.
5. Prefer removing mechanism to adding it. A fix that deletes a waterfall, a provider, or a bundle entry beats one that adds a cache, a ref, or a memo with the same measured effect.
6. Effects stay modelled. If the fix is "add another useEffect to coordinate", the flow logic wants a machine or a derived value, not another effect. See xstate and rerender-derived-state-no-effect.
7. Third-party rules are pinned, not gospel. The external catalogues are installed at reviewed commits. When a rule contradicts a primary source (React or Next.js docs) for the version actually in use, the primary source wins and the divergence is worth recording via expectations.

Anti-Patterns

• Applying rules top-down from the catalogue with no profile — "we did the CRITICAL ones" is not a diagnosis.
• A single "performance PR" bundling twenty rules, where no individual change can be attributed or reverted.
• useMemo, useCallback, or React.memo added by reflex to components that never re-rendered measurably.
• Reaching for js- micro-optimizations while an un-parallelized await chain or a barrel import dominates the trace.
• Mutating a caller's array or a shared object in the name of a hot loop.
• Weakening a schema, widening a type, or asserting past a boundary to shave milliseconds.
• Moving work to the client to make a server metric look better, or the reverse, without measuring the metric the user actually feels.
• Measuring in development mode, or on a warm cache, and reporting it as the improvement.
• Treating a bundle-size win as a user win without checking whether the removed code was on the critical path.
• Optimizing a re-render storm caused by flow logic scattered across effects, instead of modelling the flow.

Completion Check

• Is the symptom stated in user-observable terms, with a reproducible measurement method?
• Was the dominant cost attributed with evidence before a category was chosen?
• Does the diff carry one hypothesis, naming the specific rule it applies?
• Does the same measurement, run the same way, show the improvement — and would the change be reverted if it did not?
• Are all behavior tests unchanged and green, with no assertion edited to fit the optimization?
• Did every micro-optimization stay inside a proven hot path, local in scope, with immutability and typing intact at every boundary?
• Was a simpler fix — deleting the waterfall, narrowing the subscription, moving the boundary — considered before a cache was added?
• Is the before/after evidence recorded where the reviewer will see it?