web-vitals

web-vitals is a small JavaScript library from Google that measures how a website performs for the actual people visiting it. It tracks the specific signals Google uses to evaluate page experience in search rankings and developer tools, so the numbers you see in your own monitoring match what Google sees.

The library covers three Core Web Vitals that Google considers the most important: Largest Contentful Paint, which measures how long it takes for the main content of the page to appear; Interaction to Next Paint, which measures how quickly the page responds when a user clicks or taps something; and Cumulative Layout Shift, which measures how much the page layout unexpectedly moves around while loading. It also captures two additional signals: First Contentful Paint and Time to First Byte, which relate to how quickly the server starts delivering content.

You can install it from npm and import it into your JavaScript code with a couple of lines. For each metric, you provide a callback function that runs whenever a measurement is ready. From there, you decide what to do with the data: log it for debugging, send it to your own analytics system, or forward it to Google Analytics or Google Tag Manager. The library is intentionally small, roughly 2 kilobytes in its compressed form, so it adds very little overhead to your page.

A second build called the attribution build is available for teams who want to understand not just what their score is but why it is low. It attaches extra diagnostic information to each metric report pointing to the specific element or interaction that caused the poor result.

The library can be loaded via npm or directly from a CDN using a script tag. It is designed to be loaded after other content rather than early in the page, since it uses a browser feature that gives it access to performance data even when loaded late. The full README is longer than what was shown.