`web-vitals`

Overview
Installation
Usage
Bundle versions
- Which bundle is right for you?
- How the polyfill works
API
- Types
- Functions
Browser Support
Limitations
Development
License

Overview

The web-vitals library is a tiny (~1K), modular library for measuring all the Web Vitals metrics on real users, in a way that accurately matches how they're measured by Chrome and reported to other Google tools (e.g. Chrome User Experience Report, Page Speed Insights, Search Console's Speed Report).

The library supports all of the Core Web Vitals as well as all of the other Web Vitals that can be measured in the field:

Core Web Vitals

Other Web Vitals

Installation

You can install this library from npm by running:

npm install web-vitals

Note: If you're not using npm, you can still load web-vitals via <script> tags from a CDN like unpkg.com. See the load web-vitals from a CDN usage example below for details.

Usage

Load the library

There are two different versions of the web-vitals library (the "standard" version and the "base+polyfill" version), and how you load the library depends on which version you want to use.

For details on the difference between the two versions, see which bundle is right for you.

1. The "standard" version

To load the "standard" version, import modules from the web-vitals package in your application code (as you would with any npm package and node-based build tool):

import {getLCP, getFID, getCLS} from 'web-vitals';

2. The "base+polyfill" version

Loading the "base+polyfill" version is a two-step process:

First, in your application code, import the "base" build rather than the "standard" build. To do this, change any import statements that reference web-vitals to web-vitals/base:

- import {getLCP, getFID, getCLS} from 'web-vitals';
+ import {getLCP, getFID, getCLS} from 'web-vitals/base';

Then, inline the code from dist/polyfill.js into the <head> of your pages.

<!DOCTYPE html>
<html>
  <head>
    <script>
      // Inline code from `dist/polyfill.js` here
    </script>
  </head>
  <body>
    ...
  </body>
</html>

Note that the code must go in the <head> of your pages in order to work. See how the polyfill works for more details.

Tip: while it's certainly possible to inline the code in dist/polyfill.js by copy and pasting it directly into your templates, it's better to automate this process in a build step—otherwise you risk the "base" and the "polyfill" scripts getting out of sync when new versions are released.

Basic usage

Each of the Web Vitals metrics is exposed as a single function that takes an onReport callback. This callback will be called any time the metric value is available and ready to be reported.

The following example measures each of the Core Web Vitals metrics and logs the result to the console once its value is ready to report.

(The examples below import the "standard" version, but they will work with the polyfill version as well.)

import {getCLS, getFID, getLCP} from 'web-vitals';

getCLS(console.log);
getFID(console.log);
getLCP(console.log);

Note that some of these metrics will not report until the user has interacted with the page, switched tabs, or the page starts to unload. If you don't see the values logged to the console immediately, try reloading the page (with preserve log enabled) or switching tabs and then switching back.

Also, in some cases a metric callback may never be called:

FID is not reported if the user never interacts with the page.
FCP, FID, and LCP are not reported if the page was loaded in the background.

In other cases, a metric callback may be called more than once:

CLS should be reported any time the page's visibilityState changes to hidden.
CLS, FCP, FID, and LCP are reported again after a page is restored from the back/forward cache.

Warning: do not call any of the Web Vitals functions (e.g. getCLS(), getFID(), getLCP()) more than once per page load. Each of these functions creates a PerformanceObserver instance and registers event listeners for the lifetime of the page. While the overhead of calling these functions once is negligible, calling them repeatedly on the same page may eventually result in a memory leak.

Report the value on every change

In most cases, you only want onReport to be called when the metric is ready to be reported. However, it is possible to report every change (e.g. each layout shift as it happens) by setting the optional, second argument (reportAllChanges) to true.

This can be useful when debugging, but in general using reportAllChanges is not needed (or recommended).

import {getCLS} from 'web-vitals';

// Logs CLS as the value changes.
getCLS(console.log, true);

Report only the delta of changes

Some analytics providers allow you to update the value of a metric, even after you've already sent it to their servers (overwriting the previously-sent value with the same id).

Other analytics providers, however, do not allow this, so instead of reporting the new value, you need to report only the delta (the difference between the current value and the last-reported value). You can then compute the total value by summing all metric deltas sent with the same ID.

The following example shows how to use the id and delta properties:

import {getCLS, getFID, getLCP} from 'web-vitals';

function logDelta({name, id, delta}) {
  console.log(`${name} matching ID ${id} changed by ${delta}`);
}

getCLS(logDelta);
getFID(logDelta);
getLCP(logDelta);

Note: the first time the onReport function is called, its value and delta properties will be the same.

In addition to using the id field to group multiple deltas for the same metric, it can also be used to differentiate different metrics reported on the same page. For example, after a back/forward cache restore, a new metric object is created with a new id (since back/forward cache restores are considered separate page visits).

Send the results to an analytics endpoint

The following example measures each of the Core Web Vitals metrics and reports them to a hypothetical /analytics endpoint, as soon as each is ready to be sent.

The sendToAnalytics() function uses the navigator.sendBeacon() method (if available), but falls back to the fetch() API when not.

import {getCLS, getFID, getLCP} from 'web-vitals';

function sendToAnalytics(metric) {
  const body = JSON.stringify({[metric.name]: metric.value});
  // Use `navigator.sendBeacon()` if available, falling back to `fetch()`.
  (navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
      fetch('/analytics', {body, method: 'POST', keepalive: true});
}

getCLS(sendToAnalytics);
getFID(sendToAnalytics);
getLCP(sendToAnalytics);

Send the results to Google Analytics

Google Analytics does not support reporting metric distributions in any of its built-in reports; however, if you set a unique dimension value (in this case, the metric id, as shown in the examples below) on every metric instance that you send to Google Analytics, you can create a report yourself using the Google Analytics Reporting API and any data visualization library you choose.

As an example of this, the Web Vitals Report is a free and open-source tool you can use to create visualizations of the Web Vitals data that you've sent to Google Analytics.

In order to use the Web Vitals Report (or build your own custom reports using the API) you need to send your data to Google Analytics following one of the examples outlined below:

Using `analytics.js`

import {getCLS, getFID, getLCP} from 'web-vitals';

function sendToGoogleAnalytics({name, delta, id}) {
  // Assumes the global `ga()` function exists, see:
  // https://developers.google.com/analytics/devguides/collection/analyticsjs
  ga('send', 'event', {
    eventCategory: 'Web Vitals',
    eventAction: name,
    // The `id` value will be unique to the current page load. When sending
    // multiple values from the same page (e.g. for CLS), Google Analytics can
    // compute a total by grouping on this ID (note: requires `eventLabel` to
    // be a dimension in your report).
    eventLabel: id,
    // Google Analytics metrics must be integers, so the value is rounded.
    // For CLS the value is first multiplied by 1000 for greater precision
    // (note: increase the multiplier for greater precision if needed).
    eventValue: Math.round(name === 'CLS' ? delta * 1000 : delta),
    // Use a non-interaction event to avoid affecting bounce rate.
    nonInteraction: true,
    // Use `sendBeacon()` if the browser supports it.
    transport: 'beacon',
  });
}

getCLS(sendToGoogleAnalytics);
getFID(sendToGoogleAnalytics);
getLCP(sendToGoogleAnalytics);

Using `gtag.js`

import {getCLS, getFID, getLCP} from 'web-vitals';

function sendToGoogleAnalytics({name, delta, id}) {
  // Assumes the global `gtag()` function exists, see:
  // https://developers.google.com/analytics/devguides/collection/gtagjs
  gtag('event', name, {
    event_category: 'Web Vitals',
    // The `id` value will be unique to the current page load. When sending
    // multiple values from the same page (e.g. for CLS), Google Analytics can
    // compute a total by grouping on this ID (note: requires `eventLabel` to
    // be a dimension in your report).
    event_label: id,
    // Google Analytics metrics must be integers, so the value is rounded.
    // For CLS the value is first multiplied by 1000 for greater precision
    // (note: increase the multiplier for greater precision if needed).
    value: Math.round(name === 'CLS' ? delta * 1000 : delta),
    // Use a non-interaction event to avoid affecting bounce rate.
    non_interaction: true,
  });
}

getCLS(sendToGoogleAnalytics);
getFID(sendToGoogleAnalytics);
getLCP(sendToGoogleAnalytics);

Using Google Tag Manager

The following example measures each of the Core Web Vitals metrics and sends them as separate dataLayer-events to be used by Google Tag Manager. With the web-vitals trigger you send the metrics to any tag inside your account (see this comment for implementation details).

import {getCLS, getFID, getLCP} from 'web-vitals';

function sendToGTM({name, delta, id}) {
  // Assumes the global `dataLayer` array exists, see:
  // https://developers.google.com/tag-manager/devguide
  dataLayer.push({
    event: 'web-vitals',
    event_category: 'Web Vitals',
    event_action: name,
    // The `id` value will be unique to the current page load. When sending
    // multiple values from the same page (e.g. for CLS), Google Analytics can
    // compute a total by grouping on this ID (note: requires `eventLabel` to
    // be a dimension in your report).
    event_label: id,
    // Google Analytics metrics must be integers, so the value is rounded.
    // For CLS the value is first multiplied by 1000 for greater precision
    // (note: increase the multiplier for greater precision if needed).
    event_value: Math.round(name === 'CLS' ? delta * 1000 : delta),
  });
}

getCLS(sendToGTM);
getFID(sendToGTM);
getLCP(sendToGTM);

Load `web-vitals` from a CDN

The recommended way to use the web-vitals package is to install it from npm and integrate it into your build process. However, if you're not using npm, it's still possible to use web-vitals by requesting it from a CDN that serves npm package files.

The following examples show how to load web-vitals from unpkg.com, whether your targeting just modern browsers (using the "standard" version) or all browsers (using the "base+polyfill" version):

Load the "standard" version (using a module script)

<!-- Append the `?module` param to load the module version of `web-vitals` -->
<script type="module">
  import {getCLS, getFID, getLCP} from 'https://unpkg.com/web-vitals?module';

  getCLS(console.log);
  getFID(console.log);
  getLCP(console.log);
</script>

Load the "standard" version (using a classic script)

<!-- Without the `?module` param, the UMD version is loaded and sets the `webVitals` global -->
<script defer src="https://unpkg.com/web-vitals"></script>
<script>
addEventListener('DOMContentLoaded', function() {
  webVitals.getCLS(console.log);
  webVitals.getFID(console.log);
  webVitals.getLCP(console.log);
});
</script>

Load the "base+polyfill" version (using a classic script)

<!DOCTYPE html>
<html>
  <head>
    <script>
      // Inline code from `https://unpkg.com/web-vitals/dist/polyfill.js` here.
    </script>
  </head>
  <body>
    ...
    <!-- Load the UMD version of the "base" bundle. -->
    <script defer src="https://unpkg.com/web-vitals/dist/web-vitals.base.umd.js"></script>
    <script>
    addEventListener('DOMContentLoaded', function() {
      webVitals.getCLS(console.log);
      webVitals.getFID(console.log);
      webVitals.getLCP(console.log);
    });
    </script>
  </body>
</html>

Bundle versions

The web-vitals package includes builds for both the "standard" and "base+polyfill" versions, as well as different formats of each to allow developers to choose the format that best meets their needs or integrates with their architecture.

The following table lists all the bundles distributed with the web-vitals package on npm.

Filename (all within `dist/`)*	Export	Description
`web-vitals.js`	`pkg.module`	An ES module bundle of all metric functions, without any extra polyfills to expand browser support. This is the "standard" version and is the simplest way to consume this library out of the box.
`web-vitals.umd.js`	`pgk.main`	A UMD version of the `web-vitals.js` bundle (exposed on the `window.webVitals.*` namespace).
`web-vitals.base.js`	--	An ES module bundle containing just the "base" part of the "base+polyfill" version. Use this bundle if (and only if) you've also added the `polyfill.js` script to the `<head>` of your pages. See how to use the polyfill for more details.
`web-vitals.base.umd.js`	`--`	A UMD version of the `web-vitals.base.js` bundle (exposed on the `window.webVitals.*` namespace).
`polyfill.js`	--	The "polyfill" part of the "base+polyfill" version. This script should be used with either `web-vitals.base.js` or `web-vitals.base.umd.js` (it will not work with the `web-vitals.js` or `web-vitals.umd.js` bundles). See how to use the polyfill for more details.

Which bundle is right for you?

Most developers will generally want to use the "standard" bundle (either the ES module or UMD version, depending on your build system), as it's the easiest to use out of the box and integrate into existing build tools.

However, there are a few good reasons to consider using the "base+polyfill" version, for example:

FID can be measured in all browsers.
FCP, FID, and LCP will be more accurate in some cases (since the polyfill detects the page's initial visibilityState earlier).

How the polyfill works

The polyfill.js script adds event listeners (to track FID cross-browser), and it records initial page visibility state as well as the timestamp of the first visibility change to hidden (to improve the accuracy of FCP, LCP, and FID).

In order for it to work properly, the script must be the first script added to the page, and it must run before the browser renders any content to the screen. This is why it needs to be added to the <head> of the document.

The "standard" version of the web-vitals library includes some of the same logic found in polyfill.js. To avoid duplicating that code when using the "base+polyfill" version, the web-vitals.base.js bundle does not include any polyfill logic, instead it coordinates with the code in polyfill.js, which is why the two scripts must be used together.

API

Types:

`Metric`

interface Metric {
  // The name of the metric (in acronym form).
  name: 'CLS' | 'FCP' | 'FID' | 'LCP' | 'TTFB';

  // The current value of the metric.
  value: number;

  // The delta between the current value and the last-reported value.
  // On the first report, `delta` and `value` will always be the same.
  delta: number;

  // A unique ID representing this particular metric that's specific to the
  // current page. This ID can be used by an analytics tool to dedupe
  // multiple values sent for the same metric, or to group multiple deltas
  // together and calculate a total.
  id: string;

  // Any performance entries used in the metric value calculation.
  // Note, entries will be added to the array as the value changes.
  entries: (PerformanceEntry | FirstInputPolyfillEntry | NavigationTimingPolyfillEntry)[];
}

`ReportHandler`

interface ReportHandler {
  (metric: Metric): void;
}

`FirstInputPolyfillEntry`

When using the FID polyfill (and if the browser doesn't natively support the Event Timing API), metric.entries will contain an object that polyfills the PerformanceEventTiming entry:

type FirstInputPolyfillEntry = Omit<PerformanceEventTiming,
  'processingEnd' | 'processingEnd', 'toJSON'>

`FirstInputPolyfillCallback`

interface FirstInputPolyfillCallback {
  (entry: FirstInputPolyfillEntry): void;
}

`NavigationTimingPolyfillEntry`

When calling getTTFB(), if the browser doesn't support the Navigation Timing API Level 2 interface, it will polyfill the entry object using timings from performance.timing:

export type NavigationTimingPolyfillEntry = Omit<PerformanceNavigationTiming,
  'initiatorType' | 'nextHopProtocol' | 'redirectCount' | 'transferSize' |
  'encodedBodySize' | 'decodedBodySize' | 'toJSON'>

`WebVitalsGlobal`

If using the "base+polyfill" build, the polyfill.js script creates the global webVitals namespace matching the following interface:

interface WebVitalsGlobal {
  firstInputPolyfill: (onFirstInput: FirstInputPolyfillCallback) => void;
  resetFirstInputPolyfill: () => void;
  firstHiddenTime: number;
}

Functions:

`getCLS()`

type getCLS = (onReport: ReportHandler, reportAllChanges?: boolean) => void

Calculates the CLS value for the current page and calls the onReport function once the value is ready to be reported, along with all layout-shift performance entries that were used in the metric value calculation. The reported value is a double (corresponding to a layout shift value).

If the reportAllChanges param is true, the onReport function will be called any time a new layout-shift performance entry is dispatched, or once the final value of the metric has been determined.

Important: unlike other metrics, CLS continues to monitor changes for the entire lifespan of the page—including if the user returns to the page after it's been hidden/backgrounded. However, since browsers often will not fire additional callbacks once the user has backgrounded a page, onReport is always called when the page's visibility state changes to hidden. As a result, the onReport function might be called multiple times during the same page load (see Reporting only the delta of changes for how to manage this).

`getFCP()`

type getFCP = (onReport: ReportHandler, reportAllChanges?: boolean) => void

Calculates the FCP value for the current page and calls the onReport function once the value is ready, along with the relevant paint performance entry used to determine the value. The reported value is a DOMHighResTimeStamp.

`getFID()`

type getFID = (onReport: ReportHandler, reportAllChanges?: boolean) => void

Calculates the FID value for the current page and calls the onReport function once the value is ready, along with the relevant first-input performance entry used to determine the value (and optionally the input event if using the FID polyfill). The reported value is a DOMHighResTimeStamp.

Important: since FID is only reported after the user interacts with the page, it's possible that it will not be reported for some page loads.

`getLCP()`

type getLCP = (onReport: ReportHandler, reportAllChanges?: boolean) => void

Calculates the LCP value for the current page and calls the onReport function once the value is ready (along with the relevant largest-contentful-paint performance entries used to determine the value). The reported value is a DOMHighResTimeStamp.

If the reportAllChanges param is true, the onReport function will be called any time a new largest-contentful-paint performance entry is dispatched, or once the final value of the metric has been determined.

`getTTFB()`

type getTTFB = (onReport: ReportHandler, reportAllChanges?: boolean) => void

Calculates the TTFB value for the current page and calls the onReport function once the page has loaded, along with the relevant navigation performance entry used to determine the value. The reported value is a DOMHighResTimeStamp.

Note, this function waits until after the page is loaded to call onReport in order to ensure all properties of the navigation entry are populated. This is useful if you want to report on other metrics exposed by the Navigation Timing API.

For example, the TTFB metric starts from the page's time origin, which means it includes time spent on DNS lookup, connection negotiation, network latency, and unloading the previous document. If, in addition to TTFB, you want a metric that excludes these timings and just captures the time spent making the request and receiving the first byte of the response, you could compute that from data found on the performance entry:

import {getTTFB} from 'web-vitals';

getTTFB((metric) => {
  // Calculate the request time by subtracting from TTFB
  // everything that happened prior to the request starting.
  const requestTime = metric.value - metric.entries[0].requestStart;
  console.log('Request time:', requestTime);
});

Note: browsers that do not support navigation entries will fall back to using performance.timing (with the timestamps converted from epoch time to DOMHighResTimeStamp). This ensures code referencing these values (like in the example above) will work the same in all browsers.

Browser Support

The web-vitals code has been tested and will run without error in all major browsers as well as Internet Explorer back to version 9. However, some of the APIs required to capture these metrics are currently only available in Chromium-based browsers (e.g. Chrome, Edge, Opera, Samsung Internet).

Browser support for each function is as follows:

getCLS(): Chromium,
getFCP(): Chromium, Safari Technology Preview
getFID(): Chromium, Firefox, Safari, Internet Explorer (with the polyfill)
getLCP(): Chromium
getTTFB(): Chromium, Firefox, Safari, Internet Explorer

Limitations

The web-vitals library is primarily a wrapper around the Web APIs that measure the Web Vitals metrics, which means the limitations of those APIs will mostly apply to this library as well.

The primary limitation of these APIs is they have no visibility into <iframe> content (not even same-origin iframes), which means pages that make use of iframes will likely see a difference between the data measured by this library and the data available in the Chrome User Experience Report (which does include iframe content).

For same-origin iframes, it's possible to use the web-vitals library to measure metrics, but it's tricky because it requires the developer to add the library to every frame and postMessage() the results to the parent frame for aggregation.

Note: given the lack of iframe support, the getCLS() function technically measures DCLS (Document Cumulative Layout Shift) rather than CLS, if the page includes iframes).

Development

Building the code

The web-vitals source code is written in TypeScript. To transpile the code and build the production bundles, run the following command.

npm run build

To build the code and watch for changes, run:

npm run watch

Running the tests

The web-vitals code is tested in real browsers using webdriver.io. Use the following command to run the tests:

npm test

To test any of the APIs manually, you can start the test server

npm run test:server

Then navigate to http://localhost:9090/test/<view>, where <view> is the basename of one the templates under /test/views/.

You'll likely want to combine this with npm run watch to ensure any changes you make are transpiled and rebuilt.

License

Apache 2.0

isabella232 / web-vitals Goto Github PK

web-vitals's Introduction

web-vitals

Overview

Core Web Vitals

Other Web Vitals

Installation

Usage

Load the library

Basic usage

Report the value on every change

Report only the delta of changes

Send the results to an analytics endpoint

Send the results to Google Analytics

Using analytics.js

Using gtag.js

Using Google Tag Manager

Load web-vitals from a CDN

Bundle versions

Which bundle is right for you?

How the polyfill works

API

Types:

Metric

ReportHandler

FirstInputPolyfillEntry

FirstInputPolyfillCallback

NavigationTimingPolyfillEntry

WebVitalsGlobal

Functions:

getCLS()

getFCP()

getFID()

getLCP()

getTTFB()