web-vitals (JS library)
Google Chrome’s tiny (~2 KB brotli’d) JavaScript library for measuring Core Web Vitals on your own real users. It is the field-instrumentation layer of the measurement chain: where CrUX is Google’s aggregate field dataset and Lighthouse is the lab tool, web-vitals is the code you embed to collect first-party RUM — and it “accurately reflects how Chrome measures and reports these metrics” to CrUX and PageSpeed Insights, so your numbers line up with Google’s. Apache-2.0, maintained by the Chrome team.
What it measures
The three Core Web Vitals plus two supporting load metrics, each via a metric-specific callback:
| Metric | API | Good / needs-improvement / poor |
|---|---|---|
| [[core-web-vitals | LCP]] — Largest Contentful Paint | onLCP() |
| INP — Interaction to Next Paint | onINP() | ≤200 ms / ≤500 ms / >500 ms |
| CLS — Cumulative Layout Shift | onCLS() | ≤0.1 / ≤0.25 / >0.25 |
| FCP — First Contentful Paint | onFCP() | — |
| TTFB — Time to First Byte | onTTFB() | — |
Callbacks fire when each metric is ready; reportAllChanges opts into every update rather than the final
value. It builds on PerformanceObserver with the buffered flag (so it captures events from before the
script loaded) and ships data with navigator.sendBeacon() at page unload — the standard analytics wiring.
The attribution build — diagnosis in the field
An optional web-vitals/attribution import (~1.5 KB more) attaches root-cause data to each metric:
the target element, timing breakdowns, and load-state info. This is the piece that sharpens the wiki’s
“diagnose with Lighthouse (lab), judge with CrUX (field)” rule (crux, synthesis) — with
attribution you can also diagnose in the field, on the actual slow sessions, not just reproduce a
synthetic load.
Why it matters here
web-vitals is the measurement substrate core-web-vitals/core-web-vitals-seo assume but the wiki never paged. It closes a real gap left by CrUX: CrUX only covers publicly discoverable, high-traffic pages at p75 — the long tail and pre-launch pages are invisible to it. A site that embeds web-vitals gets field data on every page it serves, including the ones CrUX’s eligibility threshold omits. So the field side of the thesis isn’t only Google’s aggregate window; a team can run its own.
A small self-consistency note for the page-weight/bundle-size thesis: the instrument that polices byte budgets is itself ~2 KB — measurement doesn’t have to cost much weight.
Tier
T1 — first-party Google Chrome repo (the canonical CWV instrumentation), the spoke’s convention for a tool source (cf. lighthouse, crux). URL-only ingest. Thresholds are the current (2026-06) definitions and are volatile — INP already replaced FID in March 2024 (core-web-vitals).
Related
core-web-vitals · crux · lighthouse · inp · core-web-vitals-seo · performance-budget · synthesis