web-vitals

library5.2.0jsnpmunverified

The `web-vitals` library provides a lightweight, modular way to measure essential performance metrics, known as Web Vitals, directly in the browser. It focuses on the current Core Web Vitals (Largest Contentful Paint (LCP), Interaction to Next Paint (INP), and Cumulative Layout Shift (CLS)), as well as First Contentful Paint (FCP) and Time to First Byte (TTFB). Maintained by the Google Chrome team, this library ensures that the collected data accurately reflects how these metrics are measured by Chrome and reported in official Google tools like the Chrome User Experience Report. It is widely used for Real User Monitoring (RUM) to collect and send performance data to analytics endpoints. The library is actively developed, with its current stable version being 5.2.0, and releases generally align with updates to Web Vitals definitions and Chrome's underlying measurement methodologies.

observability

npm install web-vitals

github ↗package ↗

INSTALL

IMPORT

SIG · WEB-VITALS

web-vitals

observabilityjavascriptv5.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

onLCP, onINP, onCLS

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

✗ const { onLCP } = require('web-vitals');

Primary named exports for Core Web Vitals metrics. CommonJS `require` is not officially supported for modern versions, prefer ESM imports.

onFCP, onTTFB

✓ import { onFCP, onTTFB } from 'web-vitals';

✗ import onFCP from 'web-vitals/onFCP';

Additional named exports for other key Web Vitals. All functions are named exports from the main package.

onLCP, onINP, onCLS (Attribution build)

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

✗ import { onLCP } from 'web-vitals';

The 'attribution' build provides richer diagnostic data for debugging poor scores, imported from a specific subpath. Only use this if you need the extra data as it has a slightly larger bundle size.

This code demonstrates how to import and use `web-vitals` to measure all standard metrics (CLS, FCP, INP, LCP, TTFB) and send them to a hypothetical analytics endpoint using `navigator.sendBeacon` or `fetch` with `keepalive` for robust reporting.

import { onCLS, onFCP, onINP, onLCP, onTTFB, type Metric } from 'web-vitals'; interface AnalyticsData { name: string; value: number; id: string; navigationType: string; delta?: number; entries?: PerformanceEntry[]; } function sendToAnalytics(metric: Metric) { const analyticsEndpoint = process.env.ANALYTICS_URL ?? '/api/analytics'; const data: AnalyticsData = { name: metric.name, value: metric.value, id: metric.id, navigationType: metric.navigationType, delta: metric.delta, entries: metric.entries // Include entries for detailed analysis if needed }; // Use sendBeacon for reliable reporting on page unload (navigator.sendBeacon && navigator.sendBeacon(analyticsEndpoint, JSON.stringify(data))) || fetch(analyticsEndpoint, { body: JSON.stringify(data), method: 'POST', credentials: 'omit', keepalive: true, // Ensures request completes even if page unloads headers: { 'Content-Type': 'application/json' } }).catch(error => console.error('Failed to send analytics:', error)); console.log(`Metric Reported: ${metric.name} - Value: ${metric.value} (ID: ${metric.id})`); } // Measure all Core Web Vitals and other key metrics, sending them to analytics onCLS(sendToAnalytics); onFCP(sendToAnalytics); onINP(sendToAnalytics); onLCP(sendToAnalytics); onTTFB(sendToAnalytics); console.log('Web Vitals measurement initialized.');

Debug

Known issues

breakingThe `onFID()` function was deprecated in v3/v4 and completely removed in v5. It has been superseded by `onINP()` (Interaction to Next Paint) as the primary responsiveness metric in Core Web Vitals as of March 2024.

fix

Replace all calls to `onFID()` with `onINP()`. The `onINP()` function takes the same `reportCallback` signature.

affects: >=3.0.0

breakingAll `getXXX()` functions (e.g., `getCLS`, `getLCP`) were deprecated in v3 and removed in v4. These functions were designed for one-off measurement, whereas the `onXXX()` functions provide more accurate real-time field data by reporting updates throughout the page lifecycle.

fix

Migrate from `getXXX()` functions to their `onXXX()` counterparts (e.g., `getCLS` to `onCLS`). Ensure your analytics reporting handles multiple metric updates, especially for CLS and INP which can change over time.

affects: >=3.0.0

breakingThe browser support policy changed in v5 to 'Baseline Widely available', potentially impacting older browser versions. This means features are supported in browsers that have 95% or greater global usage for at least 6 months.

fix

Review your target browser support matrix. If you need to support very old or niche browsers, you might need to stick to an earlier `web-vitals` version or implement custom polyfills for certain `PerformanceObserver` APIs.

affects: >=5.0.0

breakingWhen using the `/attribution` build, several fields within the attribution objects for LCP, INP, and TTFB metrics were renamed in v4 and v5. For example, `eventTarget` to `interactionTarget` for INP, and various `*Time` fields to `*Duration` for LCP/TTFB.

fix

Update your analytics processing or UI code to reflect the new property names in the attribution data if you are consuming detailed diagnostic information. Refer to the `upgrading-to-v4.md` and `upgrading-to-v5.md` guides in the GitHub repository for a complete list of changes.

affects: >=4.0.0

gotchaMetrics like CLS and INP can update multiple times throughout the page's lifecycle. The `onXXX()` functions will call your callback whenever the metric's value changes or is finalized. Ensure your analytics integration is designed to handle these updates, potentially reporting the latest value (or delta) upon page unload or visibility change.

fix

Implement a robust analytics reporting strategy. It's recommended to send the final metric value and any delta upon the `pagehide` event or when the page's visibility state changes to hidden, using `navigator.sendBeacon` for reliability. The library examples demonstrate this pattern.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: document is not defined

The `web-vitals` library relies on browser-specific APIs (like `document`, `window`, `PerformanceObserver`) and is not intended to run in Node.js environments.

fix

Ensure `web-vitals` is only imported and executed in a browser context. If using a server-side rendering (SSR) framework, conditionally import or execute the `web-vitals` code only on the client side (e.g., inside `useEffect` in React, or within `window.onload` checks).

TypeError: onFID is not a function

You are attempting to use the `onFID` function which was removed in `web-vitals` v5.0.0. Interaction to Next Paint (INP) replaced First Input Delay (FID) as a Core Web Vital.

fix

Update your code to use `onINP` instead of `onFID`. You may also need to upgrade your `web-vitals` package to a version that supports `onINP` if you are on a very old version (though `onINP` has been present for a while).

Web Vitals metrics are not appearing in my analytics dashboard.

The `web-vitals` library measures metrics but does not send them to an analytics service by itself. You must provide a callback function that sends the collected `Metric` object to your chosen analytics endpoint.

fix

Implement a `sendToAnalytics` function (as shown in the quickstart example) and pass it to each `onXXX` function. Ensure this function correctly formats and dispatches the data to your analytics provider (e.g., Google Analytics, custom API) and that the endpoint is reachable and correctly configured to receive the data. Consider using `navigator.sendBeacon` for improved reliability.

Upgrade

Version history

5.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

109 hits · last 30 days

node

102

panscient.com

OpenAI (training)

Resources

githubhttps://github.com/GoogleChrome/web-vitals ↗

packagehttps://www.npmjs.com/package/web-vitals ↗