Back to Explore
GuideVibeFix editorialUpdated Nov 21, 2026

Don't trust a perfect Lighthouse score: real-user Web Vitals monitoring for your vibe project

A perfect Lighthouse score does not mean users feel it is fast. Three metrics, one 75th-percentile rule, one web-vitals library: bring in real-user data, look at the worst quarter of users first, then decide which page to fix.

A person checks a website loading speed test on a laptop, the gauge on screen showing a current speed of 94%

Scope: how this guide differs from the performance guides already published

First, let me place this guide. The site already has several performance guides, each covering its own area: vibe-project-performance-budget-guide is about setting a performance budget before launch and holding the numbers during development; vibe-project-observability-guide is about giving a one-person team "eyes and ears" with logs, metrics, and traces that show what is happening inside the system; vibe-project-session-replay-heatmap-guide is about using session recordings and heatmaps to see where users get stuck; vibe-project-caching-strategy-guide and vibe-project-image-optimization-guide cover specific optimization techniques such as caching and images. This guide does none of those things. It covers exactly one thing: how fast your site really is in the hands of real users — measured with the three Web Vitals metrics, and measured continuously, not once on launch day.

This deserves its own guide because vibe projects are easy to fool on this question. Your computer is new, your home connection is gigabit, your browser cache already holds everything, and Lighthouse gives you a 100. But your user may be on a three-year-old Android phone, on 4G in the subway, opening your site for the first time with no cache at all. Your 100 and their stuttering can both be true at the same time. This guide separates "fast as you see it" from "fast as your user feels it" and lets real-user data decide.

The sources are Google's official web.dev documentation: the Web Vitals overview (web.dev/articles/vitals), Largest Contentful Paint (web.dev/articles/lcp), Interaction to Next Paint (web.dev/articles/inp), and Cumulative Layout Shift (web.dev/articles/cls), plus the official documentation of the web-vitals JavaScript library (github.com/GoogleChrome/web-vitals). The definitions of the three metrics, the pass thresholds, the 75th-percentile rule, the difference between field and lab measurement, and how to use the library all come from these documents. The practical advice in this guide (for example, "look at the worst quarter of your users first") is built on those mechanisms, and I will say which parts are direct documentation and which parts are advice. The "Little Ledger" app used in the example is fictional and only there for demonstration.

Why a perfect lab score does not mean users feel it is fast

First, separate two kinds of measurement. Lab measurement happens in a controlled environment: the same machine, the same network, the same steps. Lighthouse, Chrome DevTools, and WebPageTest are lab tools. Their strength is stability and repeatability — change one line of code and you can immediately see whether the score moved — which makes them good for catching regressions during development. Field measurement is data collected from real users visiting the site: different phones, different networks, different habits, all mixed together, and that mixture is the truth. The web.dev overview puts it plainly: lab measurement is an essential part of delivering good experiences, but it is not a substitute for field measurement, because a site's performance can vary substantially based on a user's device capabilities, network conditions, what other processes may be running on the device, and how they interact with the page.

More specifically, two of the three Core Web Vitals are hard to measure accurately in the lab. INP measures how quickly the page gives visual feedback after a real click, tap, or key press, and nobody in the lab actually clicks those buttons the way real users do. CLS measures unexpected layout shifts over the entire lifetime of a page, while a lab run closes the page after a few seconds — a real user may keep the tab open all afternoon while late banners and asynchronously loaded content push the page around. Measuring only in the lab is like watching the dress rehearsal and skipping the actual show.

So the correct relationship is: use the lab to catch regressions while you develop, and use the field to answer "how does it actually feel to users?" This guide covers the second half: how to bring field data in, how to read it, and how to rank fixes by it. The optimization techniques themselves (how to compress images, how to split long tasks) are not covered here in depth — the site already has guides on caching, image optimization, and loading progress that each cover one piece.

What the three metrics actually measure

Web Vitals is Google's unified set of quality signals. Its core subset, Core Web Vitals, has three metrics covering three sides of the user experience: loading, interactivity, and visual stability. Each metric has a clear pass threshold, and the verdict is based on the 75th percentile — 75% of page visits must meet the target, not the average. Averages are pulled around by a few extreme values and masked by the well-behaved majority; the 75th percentile forces you to look at the worst quarter of your users. Mobile and desktop must be calculated separately, because the same page often behaves like two different sites on the two kinds of device.

The first metric is LCP, Largest Contentful Paint, which measures loading. It records when the largest image, text block, or video visible in the viewport is rendered — the moment the user feels "the main content is here." Good is 2.5 seconds or less, poor is more than 4.0 seconds, and anything in between needs improvement. Note that it measures the largest content, not the first pixel: a splash screen or loading spinner flashing first does not count; the main content appearing does. The browser keeps updating its LCP candidate as content renders, and in general you should report the most recently dispatched entry. One detail: for cross-origin images without a Timing-Allow-Origin response header, the browser can only expose the load time rather than the render time for security reasons, so the number will be slightly off.

The second metric is INP, Interaction to Next Paint, which measures interactivity. It observes all click, tap, and keyboard interactions over the whole lifespan of a page visit, and the final value is the longest interaction observed, ignoring outliers (for pages with many interactions, one worst interaction is ignored per 50 interactions). Good is 200 milliseconds or less, poor is more than 500 milliseconds. INP replaced FID (First Input Delay), which only measured the input delay of the first interaction; INP improves on it by observing all interactions, from input delay through event-handler execution to the next painted frame. An interaction's latency has three parts: input delay (the main thread is busy with something else, so your click waits in line), processing duration (how long the event callbacks themselves take), and presentation delay (the time from the callbacks finishing until the next frame is presented). Any one of the three can drag INP down, so fixing INP means looking at all three, not just one.

The third metric is CLS, Cumulative Layout Shift, which measures visual stability. It takes the largest burst of layout shift scores — a session window, where shifts occur less than 1 second apart with a maximum total window of 5 seconds — over the entire lifetime of a page. A single shift's score is the impact fraction multiplied by the distance fraction: how much area moved, and how far it moved. Good is 0.1 or less, poor is more than 0.25. The key word is "unexpected": shifts caused by the user's own actions are not bad, but shifts the user did not expect are — for example, a button about to be tapped being pushed away by a late-loading banner. Images without reserved dimensions, fonts that render larger than their fallback, and third-party widgets that resize themselves after loading are the most common sources of CLS.

Besides the three core metrics, two supporting metrics are worth collecting at the same time: TTFB (Time to First Byte), which tells you whether a bad LCP is a slow server response or a slow render, and FCP (First Contentful Paint), which tells you the difference between "nothing appeared" and "the main content did not appear." The web-vitals library supports both at the same cost, so collect them together — they save you one round of guessing when you diagnose a problem.

Step one: get your first real data without writing any code

Before writing code, use the free tools to get your first field data and confirm the problem is real. The fastest route is PageSpeed Insights (pagespeed.web.dev): enter a URL and it shows field data from the Chrome User Experience Report (CrUX) — the LCP, INP, and CLS measured from real Chrome users visiting that URL over a recent period, with the 75th percentile and pass status. If your site is verified in Search Console, its Core Web Vitals report shows the same thing, grouped by URL so you can see which pages are good and which are bad.

CrUX data has one precondition: your site needs a certain amount of real traffic before it is included. A freshly launched vibe project with little traffic will most likely find no data for itself, which is normal, not a broken tool. In that case you can look at similar pages first, or skip straight to step two and wire up the web-vitals library yourself — your own data has no traffic threshold, and a single visit produces a usable sample.

When reading CrUX data, remember the spirit of web.dev's own words: CrUX can tell you whether there is a problem, but it cannot tell you what caused it. It does not provide the detailed per-pageview telemetry needed to accurately diagnose, monitor, and quickly react to regressions. That is why web.dev strongly recommends that sites set up their own real-user monitoring. That is the core move of this guide: CrUX is the check-up report telling you which metric is red; your own RUM (real-user monitoring) is the continuous heart monitor telling you when the red light comes on, for which kind of user, and what happened just before.

Step two: wire up the web-vitals library and start collecting in a few lines

The standard way to collect your own data is Google's official web-vitals JavaScript library. It is small — the standard build is about 3K compressed — and it does exactly one thing: measure each metric using the browser's native performance APIs, in a way that accurately matches how Chrome measures them and how they are reported to other Google tools. You do not need to work through the edge cases of PerformanceObserver yourself — whether background tabs should count, whether values should reset when a page is restored from the back/forward cache, what to do when the page unloads before reporting finishes — the library already handles them. The documentation is explicit: rather than memorizing these subtleties, use the library.

Installation is one command:

npm install web-vitals

Then add these lines to your app entry point:

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

function sendToAnalytics(metric) {
  const body = JSON.stringify(metric);
  // Prefer navigator.sendBeacon, falling back to fetch.
  (navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
    fetch('/analytics', {body, method: 'POST', keepalive: true});
}

onCLS(sendToAnalytics);
onINP(sendToAnalytics);
onLCP(sendToAnalytics);

This is the standard snippet from the web.dev overview, usable as-is. Three things to note. First, loading the library can be deferred — it uses the buffered flag on PerformanceObserver, so it can read performance entries that happened before it loaded. Second, callbacks do not fire only once: CLS and INP are reported again when the page becomes hidden, and all metrics are reported again after a page is restored from the back/forward cache, so the backend must deduplicate by the same visit instead of adding them up. Third, some callbacks may never fire — no interaction means no INP, and a page kept open in a background tab means no CLS, FCP, or LCP. When aggregating, keep "no value" separate from "value is zero": the first means it never happened, the second means it happened and was good.

Projects without a build step can also load the library from a CDN with a script tag; the documentation gives examples for unpkg and jsDelivr. But it also warns that those CDNs are not affiliated with Google and there are no guarantees they will keep working — self-hosting the built files is better for security, reliability, and performance. For a vibe project, the simplest path is still npm: it sits with the rest of your dependencies and its version follows package.json.

Where the data goes, and what shape it should be stored in

Once you collect metrics, you need somewhere to receive them. The simplest approach is to add a receiving endpoint on your own backend, for example /analytics, that records each incoming report. Send with navigator.sendBeacon first: it is the browser API designed to deliver data even as the page unloads, which solves the "the user closed the page before the data finished sending" problem. The snippet above follows this idea — use sendBeacon when available, fall back to fetch with keepalive. Do not use a plain fetch without keepalive: the browser may drop the request when the page closes, and INP, whose final value is only known when the page is left, will systematically lose data.

Store at least five fields per record: the metric name (LCP, INP, CLS), the value, the page path, the device type (mobile or desktop), and the time. Name and value are the core, the page path is for locating the problem, the device type matters because mobile and desktop are judged separately, and the time is for trends and regressions. Two more fields help if you can add them: how the page was loaded (normal navigation or restored from the back/forward cache) and the network type (effectiveType, if the browser provides it). Do not store anything that identifies a specific person: no IP, no user ID, no full user-agent string. Performance data does not need to know who it was — only what kind of device, on which page, and how it performed.

When traffic grows, consider sampling: not every visit needs to be reported in full. A common approach is random sampling at 10% or 1%, reporting only the sampled visits. Sampling keeps backend load and storage costs down, but small pages already have few visits, and sampling makes it even harder to gather enough samples to compute a 75th percentile. A compromise is to split by page: core pages are sampled at full rate, long-tail pages at a lower rate. Once you set a sampling rate, do not change it often — each change breaks the historical trend, and you will not be able to line the numbers up when you review them later.

A purely static site with no backend can use an existing analytics service instead: many services have built-in support for Core Web Vitals, and those that do not usually offer custom metrics that can carry the same numbers. The only rule is that the data must land somewhere you can query, segment by page and device, and watch over time — not flash once in a one-off test run and disappear.

How to read the numbers: only the 75th percentile, and always split them up

Once the data accumulates, how you read it matters more than how you collect it. The first rule: look at the 75th percentile, not the average. Averages are fooled from both sides: a few extremely slow visits pull the average up, and a large number of good visits pull it down, hiding the users who are genuinely stuck. The 75th percentile means lining up all visits from best to worst and taking the value at the 75% position, and Google's verdict is exactly that — a page passes only when all three metrics meet their targets at the 75th percentile.

The second rule: calculate mobile and desktop separately, and page by page. Mixing mobile and desktop blends two groups with completely different experiences into one number you cannot act on. The same goes for pages: the home page, the list page, the detail page, and the checkout page each have a different LCP bottleneck. An oversized hero image on the home page and an overweight third-party script on checkout are two different problems, and averaging them together only produces a false "about average" conclusion.

The third rule: watch trends, not single points. A p75 of 2.8 seconds today and 2.6 seconds tomorrow is not an improvement; it is normal fluctuation. What you are really watching for is whether a release made a page's p75 jump and stay jumped. Draw a p75 timeline for each core page, mark releases on the same axis, and regressions become visible at a glance.

The last rule: fix the worst pages first, not the most visible ones. The home page is the shop front, but users spend their time on the feature pages. A page with a 6-second LCP that gets 20 visits a month is worth less fixing than a core page at 3.1 seconds with 2,000 visits a day. Rank by multiplying "how far from the target" by "how many visits it affects" — the further and the bigger, the sooner you fix it.

Attribution: knowing it is bad is not enough; know where it is bad

Knowing LCP is 4 seconds is not enough; you also need to know which image or script those 4 seconds went to. The web-vitals library offers an "attribution" build for this: the standard build gives you the value, and the attribution build adds diagnostic information telling you the specific cause of a poor score. Using it only means changing the import path from web-vitals to web-vitals/attribution — everything else stays identical:

import {onLCP, onINP, onCLS} from 'web-vitals/attribution';

The attribution build is about 1.5K larger compressed — still small — but the documentation recommends it only if you actually use these features. The attribution data answers concrete questions: for LCP, which element was the largest content, when it started loading, and how long loading took; for INP, which interaction was worst and which script ran longest; for CLS, which element shifted the most and when. Without attribution you can only guess; with it, guessing becomes looking it up.

Attribution data does not need to be reported in full: collect the values for every visit, but attach attribution only when a metric exceeds its threshold — for example, only include which element when LCP passes 2.5 seconds, or which script when INP passes 200 milliseconds. That locates problems without blowing up storage. When diagnosing, sort by the most frequently appearing element in the attribution data; the one at the top is usually the single most valuable fix on the whole site.

TTFB and FCP are another diagnostic aid. When LCP is bad, check TTFB first: if the first byte itself is slow, the problem is the server response and fixing rendering will not help; if TTFB is fast and FCP is fast but only LCP is slow, the problem is the largest content element itself — perhaps an image that is too large, or a font blocking the render. The two supporting metrics work like triage: find out which department the problem belongs to before deciding what to fix.

Five common misreadings

The first misreading: treating a lab score as the user experience. A Lighthouse score of 100 only says "it performed well on this machine, on this network, in this run" — not "your users feel it is fast." The lab is a regression tool for development; the field is the answer about user experience. When the two disagree, trust the field.

The second misreading: no INP value means no problem. A missing INP usually just means the user never interacted during this visit — they looked and left, or the page was opened by a crawler. No interaction means no INP, which does not mean interactions were fast; it only means nothing was measured. When judging INP pass rates, the denominator should be "visits where an interaction happened," not "all visits."

The third misreading: CLS only happens while loading. CLS is measured over the entire page lifetime, so shifts after loading count just as much. A late notification banner, asynchronously loaded recommendations, or images that load only when the user scrolls can all push the page around mid-use. Measuring CLS only during load misses most of the second half.

The fourth misreading: a slow LCP means slow images. The largest element may be an image, a text block, or a video poster. Before fixing anything, check the attribution data for what the largest element actually is: if it is a text block, the problem may be font loading; if it is a video poster, it may be when the poster loads; only if it is an image do compression, preloading, and format changes come into play. Fixing without attribution is the easiest way to fix the wrong thing.

The fifth misreading: the three metrics can compensate for each other. A good LCP does not imply a good INP, and a CLS of zero does not mean loading is fast. They are three independent sides, and the verdict requires all three to pass at the same time. Fixing works the same way: one release usually moves only one of them, so fix LCP, then look at INP — do not expect one change to fix all three at once.

Real-user Web Vitals monitoring flow: the web-vitals library collects LCP, INP, and CLS from real user visits, sends them to your own receiving endpoint, and you calculate the 75th percentile per page and device, compare against the 2.5-second, 200-millisecond, and 0.1 thresholds, then use attribution data to locate the exact element before fixing it

A complete example: the fictional "Little Ledger" in its first week after launch

Here is a full walkthrough with a fictional app called "Little Ledger." This example is invented — the app name, page names, and numbers are only for demonstration, not real data. Little Ledger is a small bookkeeping tool that wired up the web-vitals library in its first week after launch, sending data to its own /analytics endpoint.

At the end of week one, the home page numbers were: LCP at the 75th percentile was 3.4 seconds, INP was 160 milliseconds, and CLS was 0.03. Against the thresholds, INP and CLS passed; only LCP failed, still 0.9 seconds away from 2.5 seconds. Attribution showed the largest content element was the hero image at the top of the home page, which took 2.1 seconds to load, while TTFB was only 0.3 seconds — the server was fine, the image was the problem. The fix was a smaller version of the image plus preloading so it started downloading earlier. In week two, the home page LCP at the 75th percentile dropped to 2.2 seconds, passing the threshold.

The bookkeeping page that same week was the mirror image: LCP 1.8 seconds and CLS 0.01 both passed, but the INP 75th percentile was 340 milliseconds. Attribution showed the worst interaction was tapping "Save": the main thread had to run 260 milliseconds of computation before painting the next frame. The fix was to paint the feedback first — the button switching to "Saved" and the list updating locally — and move the heavy computation later. After the change, the page's INP dropped to 180 milliseconds.

Two things are worth noting in this example. First, the two pages had completely different problems — a loading problem on the home page, an interaction problem on the bookkeeping page — and averaging them into one "site-wide score" would have shown nothing. Second, each fix had a clear attribution pointer: the home page image was fixed because attribution said the largest element was that image, and the bookkeeping page computation was split because attribution said the worst interaction was stuck on that script. Without attribution, both would have been guesses.

Checklist: run through this before launch

Here is a checklist you can use directly. First, look at CrUX data in PageSpeed Insights or Search Console to confirm the problem is real before fixing an imagined slowness. Second, wire up the web-vitals library, collecting the three core metrics plus TTFB and FCP together, sending with sendBeacon first and fetch with keepalive as fallback. Third, store each record with five fields — metric name, value, page path, device type, and time — and attach attribution data for visits that exceed the thresholds. Fourth, read only the 75th percentile, split mobile from desktop and page from page, and draw timelines to catch regressions. Fifth, check attribution before fixing, confirming which element is largest, which interaction is worst, and which shift is biggest, and only then act. Sixth, a page passes only when all three metrics pass together; fix one, then look at the next — do not expect one change to solve everything.

Three more items are for when the data looks wrong. If no data arrives at all, first check whether the library actually loaded and whether the receiving endpoint returns success — do not start by doubting the metric definitions. If one page's numbers suddenly jump, compare against the release timeline first to see whether a release brought it in, then decide between rolling back and fixing. If mobile and desktop differ dramatically, first check whether it is a mobile-only problem — for example, a hero image loaded at full size on phones, or a third-party script that only runs on mobile — before touching the global configuration.

Views 6Comments 0

Comments (0)

ME
0/1000
Loading comments...

Sources

Browse projectsPublish your project

Related articles

Real photo: a bank of light gray metal filing cabinets with one drawer pulled open, revealing rows of hanging file folders inside
Guide
A real database inside the browser: IndexedDB local storage, explained plainly

localStorage only stores strings and has no indexes. IndexedDB is a real database in the browser: structured data, far larger capacity, indexes, and transactions. Following MDN's Using IndexedDB, IDBDatabase, and IDBObjectStore: the five-step routine, opening, upgrades, keys, indexes, transactions, add versus put, get, cursors, ranges, and multi-tab upgrades.

Tool TipsData WorkflowsFrontend Engineering
Real photo: hands typing on a MacBook Pro showing JavaScript code that changes HTML content, with a white mouse, papers, and binders on a white desk
Guide
Functions without the confusion: JavaScript functions, parameters, and arrow functions, explained plainly

You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.

Tool TipsFrontend EngineeringAI Coding
Real photo: a Casio scientific calculator on a wooden desk showing 123456789 + 987654321 = 1111111110, beside handwritten math notebooks, a pen, a mug, and a laptop edge
Guide
Don't let 0.1 + 0.2 break your bill: JavaScript numbers and Math, explained plainly

Numbers in JavaScript are one type, Number, stored as 64-bit floats — which is why 0.1 + 0.2 is 0.30000000000000004. This guide follows MDN's Basic math in JavaScript, Math, and Number: one number type, float error, counting money in cents, converting strings, NaN and Infinity, safe integers, the four rounding methods, Math.random, the Math toolbox, and formatting for display.

Tool TipsFrontend EngineeringAI Coding