Web Performance

Measure real users first, fix the metric that is actually failing, and verify with the same measurement. Never optimize by guesswork or by chasing a desktop Lighthouse score on a fast laptop.

Targets

Core Web Vitals are judged at the 75th percentile of page loads, separately for mobile and desktop.

Diagnostic (not Core Web Vitals): TTFB ≤ 0.8 s and FCP ≤ 1.8 s are considered good.

Workflow

1. Get field data. Use the project's RUM if it has one, then PageSpeed Insights (shows CrUX field data when the site has enough traffic) and the Search Console Core Web Vitals report. If there is no field data, add the web-vitals library (below).
2. Find the worst metric and page template at p75 on mobile. Work on that first.
3. Reproduce in the lab against a production build, never the dev server. Use the Chrome DevTools Performance panel with CPU throttling (4x or more) and network throttling, or Lighthouse (npx lighthouse https://example.com --view). A plain Lighthouse page load can't measure INP because nobody interacts; record the slow interaction with the DevTools Performance panel or a Lighthouse timespan, and use Total Blocking Time as a load-time proxy.
4. Apply the fixes for that metric (sections below). One change at a time, re-measure after each.
5. Verify in the field after deploy. CrUX is a 28-day rolling window, so RUM shows results sooner.
6. Lock it in with budgets in CI so it doesn't regress.

Field measurement with web-vitals

import { onCLS, onINP, onLCP } from "web-vitals";

function send(metric) {
  const body = JSON.stringify({
    name: metric.name,
    value: metric.value,
    rating: metric.rating,
    id: metric.id,
    page: location.pathname,
  });
  if (!navigator.sendBeacon?.("/analytics/vitals", body)) {
    fetch("/analytics/vitals", { method: "POST", body, keepalive: true });
  }
}

onCLS(send);
onINP(send);
onLCP(send);

To learn why a metric is slow (which element, which interaction), import from web-vitals/attribution and send the attribution fields you need; check the installed version's docs for their names. Aggregate at p75 per page template and device type, not averages.

Fixing LCP

First find the LCP element (Lighthouse "Largest Contentful Paint element", or the Performance panel). Then break the time into four parts and fix the biggest:

<img
  src="/img/hero-1200.avif"
  srcset="/img/hero-800.avif 800w, /img/hero-1200.avif 1200w, /img/hero-2000.avif 2000w"
  sizes="100vw"
  width="1200" height="600"
  fetchpriority="high"
  alt="Team reviewing a dashboard">

Never put loading="lazy" on the LCP image. Lazy-load only below-the-fold images.

Fixing INP

1. Find the slow interactions: field attribution from web-vitals/attribution, or record the interaction in the Performance panel and look at the Interactions track.
2. Split the time into input delay (main thread busy when the user clicked), processing (your handlers) and presentation delay (render and paint after).
3. Fix:

   • Break up long tasks (over 50 ms). Do the visible update first and yield before the rest:

     function yieldToMain() {
       if (globalThis.scheduler?.yield) return scheduler.yield();
       return new Promise((resolve) => setTimeout(resolve, 0));
     }
     
     button.addEventListener("click", async () => {
       showSpinner();          // visible feedback first
       await yieldToMain();
       await applyFilters();   // heavier work after the next paint
     });

   • Ship less JavaScript: code split by route, lazy-load heavy components used only after interaction, remove unused dependencies.
   • Tame third-party scripts (tag managers, chat widgets, A/B testing): load them with async/defer or after page load, and remove ones nobody uses.
   • Avoid layout thrashing: batch DOM reads before writes; don't read offsetHeight in a loop that also writes styles.
   • Reduce render work: virtualize long lists, use content-visibility: auto for off-screen sections, keep the DOM size reasonable. In React, wrap non-urgent updates in startTransition.

Fixing CLS

• Give every img, video and iframe width and height attributes, or a CSS aspect-ratio.
• Reserve space (min-height) for ads, embeds, cookie banners and late-loading components. Prefer overlays for banners instead of pushing content down.
• Don't insert content above existing content unless it is a direct response to a user action (shifts within 500 ms of an input don't count).
• Fonts: preload the one or two critical font files, use font-display: swap with metric overrides (size-adjust, ascent-override) on the fallback, or font-display: optional.
• Animate with transform and opacity, never top, left, width or height.

JavaScript and bundles

Look for: duplicate copies of a library, whole libraries imported for one function, large polyfills for browsers you don't support, locale or icon packs bundled in full, and code for one route shipped on every route. Split with dynamic import() and the framework's lazy-loading.

Caching and delivery

Also: serve over HTTP/2 or HTTP/3 with Brotli or gzip, preconnect to the one or two third-party origins needed early, and keep pages eligible for the back/forward cache (avoid unload handlers).

Budgets in CI

Lighthouse CI (npx @lhci/cli autorun) with a lighthouserc.json:

{
  "ci": {
    "collect": {
      "startServerCommand": "npm run start",
      "url": ["http://localhost:3000/"],
      "numberOfRuns": 3
    },
    "assert": {
      "assertions": {
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
        "total-blocking-time": ["warn", { "maxNumericValue": 200 }]
      }
    }
  }
}

Add a bundle-size budget too (for example size-limit, or the bundler's size warnings) so JavaScript growth fails the PR that causes it.

Anti-patterns

• Measuring the dev server or a fast desktop and calling it done.
• Optimizing the score instead of the metric: a 100 in the lab means little if p75 field LCP fails.
• Lazy-loading everything, including the hero image.
• Preloading many resources: they compete with the LCP resource. Preload only what is critical and discovered late.
• Averages instead of p75, or mixing mobile and desktop data.
• Ignoring third-party scripts, often the largest share of main-thread time.
• One-off fixes with no budget: performance regresses within a few releases.

Done when

• The failing metric is "good" at p75 in field data for the affected template (or lab shows the fix and field verification is scheduled).
• Each change was measured before and after on a production build with throttling.
• A CI budget covers the metric or bundle size that was fixed.

References

• references/checklist.md — read when auditing a whole page or site, or before a launch, for the full checklist by area (server, HTML, images, fonts, JavaScript, CSS, third parties, caching, monitoring).