Skip to content

ericrisco/rsc-harness / skills/performance

performance

Unverified

Use when a page or interaction is slow for one user and the fix starts from a measurement — a failing Core Web Vital (LCP, INP, CLS), a heavy JS bundle, wasted re-renders, an over-broad client boundary: profile, attribute the cost to one phase, fix it, re-measure. NOT surviving concurrent load (that is `scaling`), NOT the slow query (that is `postgresdb`).

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

SymptomMetric / phaseFirst probeFirst leverDeep fix lives in
Slow load, hero appears lateLCPLighthouse + DevTools traceattribute to a subpart, then fix that onethis skill / ../postgresdb/SKILL.md if TTFB
Janky scroll, laggy typing/clickINPDevTools Performance trace (long-task bars)break the >50 ms task, yieldthis skill
Layout jumps as it loadsCLSLighthouse layout-shift tracereserve space (dimensions / aspect-ratio)this skill
"First Load JS is huge"bundle bytes@next/bundle-analyzer / source-map-explorerkill/replace the heavy dep, then dynamic importthis skill
Component re-renders constantlyrender timeReact DevTools Profiler ("why did this render")fix the unstable ref / boundary../react/SKILL.md for the pattern
'use client' drags server work downFirst Load JSbundle analyzer server/client tracepush the boundary to a leaf../nextjs/SKILL.md
Slow only under concurrent loadthroughput, not latencyload test— not this skill —../scaling/SKILL.md
TTFB dominated by one queryserver timequery plan / EXPLAIN— not this skill —../postgresdb/SKILL.md

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)

MetricGoodNeeds improvementPoor
LCP≤ 2.5 s2.5–4.0 s> 4.0 s
INP≤ 200 ms200–500 ms> 500 ms
CLS≤ 0.10.1–0.25> 0.25

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.

SubpartWhat it isThe fix that moves it
TTFBserver + network to first byteserver work — punt to ../postgresdb/SKILL.md (slow query) or ../scaling/SKILL.md (under load); cache the response
Resource load delaygap between TTFB and the LCP resource starting to loaddiscoverability — <link rel="preload">, fetchpriority="high", never lazy-load the hero
Resource load durationtime to actually download the LCP resourcesmaller/next-gen image, CDN, right dimensions, priority on next/image
Element render delayresource downloaded but not yet paintedunblock the main thread / render-blocking CSS/JS, font readiness

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.

CLS — reserve the space

CLS comes from space that was not reserved before content arrived: images/video/ads/embeds without dimensions, content injected above existing content, and font swaps (FOUT). Fix by reserving the box up front.

<!-- Bad: no dimensions, image reflows everything below it on load -->
<img src="/card.webp" alt="" />

<!-- Good: explicit box, zero shift -->
<img src="/card.webp" width="400" height="300" alt="" />
/* Reserve space for ratio-based media and swap fonts without reflow */
.media { aspect-ratio: 16 / 9; }                 /* box exists before load */
@font-face { font-family: Inter; font-display: optional; size-adjust: 100%; }

Rules: give every image/embed explicit width/height or an aspect-ratio; render skeleton boxes the size of the real content; never insert banners/notices above content the user is already reading (push them below or overlay); use font-display: optional (or swap + size-adjust) so a font swap doesn't reflow text.

Bundle size — analyze before you cut

Never guess what's heavy. Generate a treemap, read it, then cut the biggest box.

# Next.js: interactive treemap with server/client import tracing (Turbopack module graph)
ANALYZE=true npm run build      # with @next/bundle-analyzer wired in next.config

# Any webpack/Vite build: attribute bytes back to source via source maps
npx source-map-explorer 'dist/**/*.js'

Levers in order of payoff:

  1. Kill or replace the heavy dependency. The treemap usually shows one or two boxes dwarfing everything (a date library, an icon set, a charting lib). Replace with a lighter one or a few lines of your own.
  2. Dynamic import() for non-critical UI. Modals, editors, charts, anything below the fold or behind an interaction loads on demand instead of in First Load JS.
  3. Fix tree-shaking — stop importing the whole library for one function. import _ from "lodash" pulls the entire library; import the one function (or use the native equivalent).
// Bad: whole library in the initial bundle for one helper
import _ from "lodash";
const fn = _.debounce(save, 300);

// Good: named import (tree-shakeable) — or just write the 6-line debounce
import debounce from "lodash-es/debounce";
const fn = debounce(save, 300);
// Bad: heavy editor in First Load JS even though it's behind a button
import { RichEditor } from "@org/rich-editor";

// Good: split it out, load on demand
import dynamic from "next/dynamic";
const RichEditor = dynamic(() => import("@org/rich-editor"), { ssr: false });

Render cost — React 19, the compiler, and the boundary

React 19 with the React Compiler auto-memoizes, so blanket defensive useMemo/useCallback/memo is now an anti-pattern, not a best practice — it adds noise and the compiler already handles the common cases. Manual memo is the exception, and you justify it with a profile.

  • Profile with the React DevTools Profiler: record an interaction, find the component that re-rendered, read "why did this render" and its render time.
  • The 16 ms rule: one frame at 60 fps is ~16 ms. If a manual memo saves less than that, skip it — you can't see it and you're paying for the cache.
  • The compiler cannot fix a new object/array/function reference created in render and passed as a prop — that's a fresh identity every time. Hoist it or derive it stably; that's the real fix, not wrapping the consumer in memo.

RSC boundary discipline. React Server Components ship zero JS for non-interactive trees; teams report 50–70% First-Load-JS cuts from full RSC adoption. The 'use client' directive is a boundary: everything imported below it becomes client code. So push interactivity into the smallest leaf component and keep data fetching and layout on the server.

// Bad: 'use client' at the top of the route — the whole tree ships to the browser
"use client";
export default function ProductPage({ data }) {
  /* layout, data display, and one tiny button all client-side */
}

// Good: server component holds data/layout; only the interactive leaf is a client component
export default function ProductPage({ data }) {       // server: zero JS
  return (
    <article>
      <ProductDetails data={data} />                  {/* server */}
      <AddToCartButton id={data.id} />                {/* the only 'use client' file */}
    </article>
  );
}

Use streaming SSR with <Suspense> to flush the static shell immediately and stream slow subtrees in parallel — multiple independent boundaries stream concurrently, cutting time-to-first-paint when one section is data-bound. The canonical App-Router data and component patterns are ../nextjs/SKILL.md and ../react/SKILL.md; bring the perf loop here, take the idioms there.

Anti-patterns

Anti-patternWhy it's wrongDo instead
Optimizing on a hunch, no profileyou fix a phase nobody waits onmeasure → attribute → fix the dominant phase
Chasing a lab score no real user hitslab cold-cache LCP ≠ field p75optimize the field 75th-percentile number
Reporting the mean, not p75the average hides the tail users feelalways read/report the 75th percentile
Blanket useMemo/useCallback in React 19the compiler already memoizes; you add noisememo only what the Profiler proves >16 ms
Lazy-loading the LCP / hero imageyou defer the very element LCP measurespriority / fetchpriority=high, eager
import _ from "lodash" for one functionthe whole library lands in First Load JSnamed import or a few lines of your own
'use client' at the top of the treethe entire subtree ships to the browserpush the boundary to the interactive leaf
Images/embeds with no reserved spacecontent reflows on load → CLSexplicit width/height or aspect-ratio
Micro-optimizing a non-bottleneck phaseeffort moves a number off the critical pathfix only the phase the trace points at
"Done" without re-measuringthe fix may not have moved the metricre-measure against the threshold, then stop
Reporting source-only review as a measured winno trace/field/benchmark ran, so the number is inventedlabel POTENTIAL and name the measurement
Changing three levers in one experimentyou cannot attribute the result or reuse the learningone hypothesis/change per card, then re-measure
Keeping a neutral optimizationcomplexity rose but the target did not beat normal variancetargeted revert; retain the failed-experiment record

Stop rule

You are done when the field 75th percentile clears the "good" threshold (LCP ≤ 2.5 s, INP ≤ 200 ms, CLS ≤ 0.1) and your bundle is under its budget — re-measure to confirm, then stop. Going from "good" to "slightly better good" is gold-plating: it costs maintenance and moves a number no user notices. Commit the threshold as a budget so it can't silently regress (scripts/verify.sh lints that budget; see references/profiling-playbook.md for the field-RUM wiring that keeps the p75 honest in production).

deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexVerifiedInstall