Performance

Performance: make one thing fast

Performance makes a single request, page, or interaction faster for one user. Scaling makes many requests survive at the same time. Different problem, different toolbox — if the system is fine for you and only bends under concurrent load, that is ../scaling/SKILL.md, not this.

The whole job in one line: measure with a profiler → attribute the cost to one specific phase → apply the one fix that moves that phase → re-measure against a number. Repeat until you clear the threshold, then stop.

Prime directive: no fix without a profile first. A waterfall, a flame chart, a bundle treemap, or a field CWV number comes before you touch code. The fix you guess is almost never the fix the measurement points at, and a "fast" change that moves a phase nobody was waiting on is wasted work that you then have to maintain.

Cross-reference, don't duplicate: the last column of the table below names where each deep fix lives. The one case it has no row for — you decided what to cache to cut a phase and now need that cache race-free — is ../redis/SKILL.md.

Decision table — symptom to first move

Step 0 — measure first: field vs lab

You have two kinds of measurement and they answer different questions. Use both, in this order.

• Field data (CrUX, RUM via the web-vitals library) at the 75th percentile tells you what real users actually feel. A metric passes when ≥75% of page views hit "good". This is the only number that matters for "is it actually a problem".
• Lab data (Lighthouse, the Chrome DevTools Performance trace) tells you why — it reproduces one load under controlled conditions so you can read the waterfall and flame chart.

Rule: never optimize a lab number that no real user ever hits, and never report the mean — report the 75th percentile. A lab Lighthouse run on a throttled cold cache can show an LCP your field p75 never sees; chasing it burns time on a phantom. Conversely a field INP failure with a clean lab run means you have not reproduced the slow interaction yet — go find it.

The output of Step 0 is one sentence naming the bottleneck: "LCP is 3.8 s and 2.1 s of it is resource load delay because the hero image is lazy-loaded." Do not proceed without that sentence. Tool runbooks (Lighthouse CI flags, reading a flame chart, the Profiler workflow, wiring web-vitals for RUM) live in references/profiling-playbook.md.

Measurement honesty: static source can identify a plausible bottleneck, never a measured LCP/INP/CLS, latency win or byte saving. If runtime/field data is unavailable, label the finding POTENTIAL, name the exact trace/benchmark needed, and make no numeric improvement claim. Do not turn code inspection into fictional telemetry.

Keep one experiment card per change:

metric + conditions | baseline distribution | one hypothesis/change | after distribution | keep/revert | next

Use the same device, data volume, cache state, build mode and sampling method before and after. Repeat enough runs to see ordinary variance; a one-off result inside that noise is neutral. Keep a change only when it moves the target beyond the noise without violating another budget. Revert a neutral or worse experiment with a targeted edit and preserve the card — failed attempts prevent the next person from paying for the same guess.

CWV "good" thresholds (field p75)

INP replaced FID as a Core Web Vital in March 2024 and is still a CWV — it measures the full interaction-to-next-paint, so a fast event handler with a slow paint still fails. As of 2025, ~62% of mobile pages hit good LCP (up from 44% in 2022), and LCP remains the hardest CWV to pass and the most common overall bottleneck — so start there when the symptom is "slow load".

LCP — attribute to a subpart before fixing

LCP is not one thing. It decomposes into four sequential phases, and each phase has a different fix. Attribute first, then fix only the dominant phase.

A text-node LCP rendered in a system font has zero load delay and zero load duration — its budget is all TTFB and render delay, so don't go hunting for an image to preload.

The single most common LCP mistake is lazy-loading the largest element. Make it eager and high priority:

<!-- Bad: the hero is the LCP element and you just deferred it -->
<img src="/hero.webp" loading="lazy" alt="Product" />

<!-- Good: eager + high priority + reserved dimensions (also kills CLS) -->
<link rel="preload" as="image" href="/hero.webp" fetchpriority="high" />
<img src="/hero.webp" fetchpriority="high" width="1200" height="630" alt="Product" />

// Next.js: `priority` sets fetchpriority=high and disables lazy-loading for the LCP image
import Image from "next/image";
<Image src="/hero.webp" width={1200} height={630} priority alt="Product" />;

INP — kill the long task

INP is dominated by long tasks: any main-thread task over 50 ms blocks every interaction for its full duration. The fix is to break long work into chunks under 50 ms and yield to the main thread between them so a queued click or keypress can run.

// Bad: one 400ms loop blocks every click/keypress while it runs
function processAll(items: Item[]) {
  for (const item of items) heavyWork(item); // one long task
}

// Good: chunk + yield. scheduler.yield() resumes at the FRONT of the queue,
// so your continuation isn't starved behind newly-queued work.
async function processAll(items: Item[]) {
  for (let i = 0; i < items.length; i++) {
    heavyWork(items[i]);
    if (i % 50 === 0 && "scheduler" in globalThis) {
      await (globalThis as any).scheduler.yield();
    }
  }
}

Other INP levers, in order of payoff:

• Move third-party JS off the main thread (analytics, chat widgets, tag managers) — defer, load on interaction, or sandbox in a worker. Third-party scripts are the usual hidden long-task source.
• Defer non-urgent handler work. Do the visible state update now; push the expensive recompute behind requestIdleCallback, a debounce, or startTransition.
• Measure the actual interaction — the field INP failure names which interaction; reproduce it in a DevTools trace and read the long-task bar, don't guess.