web-perf

Web Performance

Knowledge of the metrics, the thresholds, and the levers that move them. Use this when the user asks for perf review, mentions Lighthouse, or describes slow page load / janky interaction.

Core Web Vitals — Thresholds

Where the wins are (in order)

1. LCP — almost always a network problem

• Hero image not preloaded → add <link rel="preload" as="image"> or <Image priority> in Next.js
• Hero image too big → use WebP/AVIF, correct sizes attribute, responsive srcset
• Render-blocking CSS → inline critical CSS, defer the rest (media="print" onload="this.media='all'" trick or Next.js does it automatically)
• Render-blocking JS → async/defer on <script>, or move non-critical to next/dynamic
• Web font swap → font-display: swap + preload the font file; next/font does this for you

2. INP — JavaScript blocking the main thread

• Hydration cost → server-render more, hydrate less. In Next, prefer Server Components for static content
• Long tasks in event handlers → break with requestIdleCallback or split work into setTimeout(0) chunks
• Heavy third-party scripts → load after hydration with next/script strategy="lazyOnload" or defer
• Bundle bloat → see [[react-perf-kit]] bundle-* rules — barrel imports, dynamic imports, conditional loads

3. CLS — visual stability

• Images without dimensions → always set width/height (or fill with reserved aspect ratio)
• Injected content → reserve space for ads, banners, embeds
• Font swap shift → font-display: optional if shift is intolerable, else accept the FOUT
• Late-loaded fonts → preload, or use size-adjust descriptor to match fallback metrics

Network analysis checklist

Walk the network tab (or codebase) looking for:

1. Render-blocking resources: JS/CSS in <head> without async/defer/media attributes
2. Network chains: resources discovered late because they depend on others (CSS imports, JS-loaded fonts)
3. Missing preloads: critical resources (fonts, hero images, key scripts) not preloaded
4. Caching gaps: missing or weak Cache-Control, ETag, or Last-Modified headers
5. Large payloads: uncompressed or oversized JS/CSS bundles
6. Unused preconnects: preconnect directives where zero requests went to that origin

Framework / bundler detection (when reviewing an existing codebase)

Then check package.json scripts + dependencies. For Next-specific perf rules, defer to [[react-perf-kit]].

What to say when reporting

• Quantify impact: "compress hero.png (450KB) → WebP (~80KB)" beats "optimize images"
• Be specific: name the file and the metric it moves
• Skip non-issues: if LCP is 1.4s, say so — don't invent problems
• One change, one metric: don't bundle unrelated suggestions

Verification

The authoritative tool is Chrome DevTools (or its MCP version, when available). When you don't have it, fall back to:

• Read the source tree for the patterns above
• Inspect <Head> / metadata routes for preload/preconnect tags
• Check package.json for known-heavy libs (moment, lodash whole-package, large icon sets)

Don't claim a fix improved a metric without measuring — see [[evidence-before-claim]].

See also: [[react-perf-kit]], [[motion-perf]], [[seo-meta-kit]].