Web Vitals Measurement Library

Common errors

• ReferenceError: document is not defined

  cause 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

  cause 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.

  cause 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.

Warnings

• breaking The `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.
• breaking All `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.
• breaking The 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.
• breaking When 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.
• gotcha Metrics 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.

Install

• npm install web-vitals npm
• yarn add web-vitals yarn
• pnpm add web-vitals pnpm

Imports

• onLCP, onINP, onCLS
  wrong:

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

  correct:

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

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

  import onFCP from 'web-vitals/onFCP';

  correct:

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

  Additional named exports for other key Web Vitals. All functions are named exports from the main package.
• onLCP, onINP, onCLS (Attribution build)
  wrong:

  import { onLCP } from 'web-vitals';

  correct:

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

  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.

Quickstart

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.');