UNPKG

28.4 kBMarkdownView Raw
1# `web-vitals`
2
3- [Overview](#overview)
4- [Installation](#installation)
5- [Usage](#usage)
6 - [Load the library](#load-the-library)
7 - [Basic usage](#basic-usage)
8 - [Report the value on every change](#report-the-value-on-every-change)
9 - [Report only the delta of changes](#report-only-the-delta-of-changes)
10 - [Send the results to an analytics endpoint](#send-the-results-to-an-analytics-endpoint)
11 - [Send the results to Google Analytics](#send-the-results-to-google-analytics)
12 - [Send the results to Google Tag Manager](#send-the-results-to-google-tag-manager)
13 - [Load `web-vitals` from a CDN](#load-web-vitals-from-a-cdn)
14- [Bundle versions](#bundle-versions)
15 - [Which bundle is right for you?](#which-bundle-is-right-for-you)
16 - [How the polyfill works](#how-the-polyfill-works)
17- [API](#api)
18 - [Types](#types)
19 - [Functions](#functions)
20- [Browser Support](#browser-support)
21- [Limitations](#limitations)
22- [Development](#development)
23- [License](#license)
24
25## Overview
26
27The `web-vitals` library is a tiny (~1K), modular library for measuring all the [Web Vitals](https://web.dev/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](https://developers.google.com/web/tools/chrome-user-experience-report), [Page Speed Insights](https://developers.google.com/speed/pagespeed/insights/), [Search Console's Speed Report](https://webmasters.googleblog.com/2019/11/search-console-speed-report.html)).
28
29The library supports all of the [Core Web Vitals](https://web.dev/vitals/#core-web-vitals) as well as all of the [other Web Vitals](https://web.dev/vitals/#other-web-vitals) that can be measured [in the field](https://web.dev/user-centric-performance-metrics/#how-metrics-are-measured):
30
31### Core Web Vitals
32
33- [Cumulative Layout Shift (CLS)](https://web.dev/cls/)
34- [First Input Delay (FID)](https://web.dev/fid/)
35- [Largest Contentful Paint (LCP)](https://web.dev/lcp/)
36
37### Other Web Vitals
38
39- [First Contentful Paint (FCP)](https://web.dev/fcp/)
40- [Time to First Byte (TTFB)](https://web.dev/time-to-first-byte/)
41
42## Installation
43
44You can install this library from npm by running:
45
46```sh
47npm install web-vitals
48```
49
50_**Note:** If you're not using npm, you can still load `web-vitals` via `<script>` tags from a CDN like [unpkg.com](https://unpkg.com). See the [load `web-vitals` from a CDN](#load-web-vitals-from-a-cdn) usage example below for details._
51
52## Usage
53
54### Load the library
55
56There 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.
57
58For details on the difference between the two versions, see <a href="#which-version-is-right-for-you">which version is right for you</a>.
59
60**1. The "standard" version**
61
62To 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):
63
64```js
65import {getLCP, getFID, getCLS} from 'web-vitals';
66```
67
68**2. The "base+polyfill" version**
69
70Loading the "base+polyfill" version is a two-step process:
71
72First, 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`:
73
74```diff
75- import {getLCP, getFID, getCLS} from 'web-vitals';
76+ import {getLCP, getFID, getCLS} from 'web-vitals/base';
77```
78
79Then, inline the code from `dist/polyfill.js` into the `<head>` of your pages.
80
81```html
82<!DOCTYPE html>
83<html>
84 <head>
85 <script>
86 // Inline code from `dist/polyfill.js` here
87 </script>
88 </head>
89 <body>
90 ...
91 </body>
92</html>
93```
94
95Note that the code _must_ go in the `<head>` of your pages in order to work. See [how the polyfill works](#how-the-polyfill-works) for more details.
96
97_**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._
98
99### Basic usage
100
101Each 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.
102
103The following example measures each of the Core Web Vitals metrics and logs the result to the console once its value is ready to report.
104
105_(The examples below import the "standard" version, but they will work with the polyfill version as well.)_
106
107```js
108import {getCLS, getFID, getLCP} from 'web-vitals';
109
110getCLS(console.log);
111getFID(console.log);
112getLCP(console.log);
113```
114
115Note 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](https://developers.google.com/web/tools/chrome-devtools/console/reference#persist) enabled) or switching tabs and then switching back.
116
117Also, in some cases a metric callback may never be called:
118
119- FID is not reported if the user never interacts with the page.
120- FCP, FID, and LCP are not reported if the page was loaded in the background.
121
122In other cases, a metric callback may be called more than once:
123
124- CLS should be reported any time the [page's `visibilityState` changes to hidden](https://developers.google.com/web/updates/2018/07/page-lifecycle-api#advice-hidden).
125- CLS, FCP, FID, and LCP are reported again after a page is restored from the [back/forward cache](https://web.dev/bfcache/).
126
127_**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._
128
129### Report the value on every change
130
131In 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`.
132
133This can be useful when debugging, but in general using `reportAllChanges` is not needed (or recommended).
134
135```js
136import {getCLS} from 'web-vitals';
137
138// Logs CLS as the value changes.
139getCLS(console.log, true);
140```
141
142### Report only the delta of changes
143
144Some 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`).
145
146Other 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.
147
148The following example shows how to use the `id` and `delta` properties:
149
150```js
151import {getCLS, getFID, getLCP} from 'web-vitals';
152
153function logDelta({name, id, delta}) {
154 console.log(`${name} matching ID ${id} changed by ${delta}`);
155}
156
157getCLS(logDelta);
158getFID(logDelta);
159getLCP(logDelta);
160```
161
162_**Note:** the first time the `onReport` function is called, its `value` and `delta` properties will be the same._
163
164In 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).
165
166### Send the results to an analytics endpoint
167
168The 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.
169
170The `sendToAnalytics()` function uses the [`navigator.sendBeacon()`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon) method (if available), but falls back to the [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API when not.
171
172```js
173import {getCLS, getFID, getLCP} from 'web-vitals';
174
175function sendToAnalytics(metric) {
176 const body = JSON.stringify({[metric.name]: metric.value});
177 // Use `navigator.sendBeacon()` if available, falling back to `fetch()`.
178 (navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
179 fetch('/analytics', {body, method: 'POST', keepalive: true});
180}
181
182getCLS(sendToAnalytics);
183getFID(sendToAnalytics);
184getLCP(sendToAnalytics);
185```
186
187### Send the results to Google Analytics
188
189Google 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`) on every metric instance that you send to Google Analytics, including that dimension in a custom report will allow you to construct a distribution manually.
190
191Using the [Google Analytics Reporting API](https://developers.google.com/analytics/devguides/reporting) and a tool like [Data Studio](https://datastudio.google.com/) (or your own visualization library), you can create dashboards with histograms reporting quantile data (the 75th percentile is recommended) for all of the Web Vitals metrics.
192
193The following code examples show how to send your metrics to Google Analytics in order to enable reporting quantile data:
194
195#### Using `analytics.js`
196
197```js
198import {getCLS, getFID, getLCP} from 'web-vitals';
199
200function sendToGoogleAnalytics({name, delta, id}) {
201 // Assumes the global `ga()` function exists, see:
202 // https://developers.google.com/analytics/devguides/collection/analyticsjs
203 ga('send', 'event', {
204 eventCategory: 'Web Vitals',
205 eventAction: name,
206 // Google Analytics metrics must be integers, so the value is rounded.
207 // For CLS the value is first multiplied by 1000 for greater precision
208 // (note: increase the multiplier for greater precision if needed).
209 eventValue: Math.round(name === 'CLS' ? delta * 1000 : delta),
210 // The `id` value will be unique to the current page load. When sending
211 // multiple values from the same page (e.g. for CLS), Google Analytics can
212 // compute a total by grouping on this ID (note: requires `eventLabel` to
213 // be a dimension in your report).
214 eventLabel: id,
215 // Use a non-interaction event to avoid affecting bounce rate.
216 nonInteraction: true,
217 // Use `sendBeacon()` if the browser supports it.
218 transport: 'beacon',
219 });
220}
221
222getCLS(sendToGoogleAnalytics);
223getFID(sendToGoogleAnalytics);
224getLCP(sendToGoogleAnalytics);
225```
226
227#### Using `gtag.js`
228
229```js
230import {getCLS, getFID, getLCP} from 'web-vitals';
231
232function sendToGoogleAnalytics({name, delta, id}) {
233 // Assumes the global `gtag()` function exists, see:
234 // https://developers.google.com/analytics/devguides/collection/gtagjs
235 gtag('event', name, {
236 event_category: 'Web Vitals',
237 // Google Analytics metrics must be integers, so the value is rounded.
238 // For CLS the value is first multiplied by 1000 for greater precision
239 // (note: increase the multiplier for greater precision if needed).
240 value: Math.round(name === 'CLS' ? delta * 1000 : delta),
241 // The `id` value will be unique to the current page load. When sending
242 // multiple values from the same page (e.g. for CLS), Google Analytics can
243 // compute a total by grouping on this ID (note: requires `eventLabel` to
244 // be a dimension in your report).
245 event_label: id,
246 // Use a non-interaction event to avoid affecting bounce rate.
247 non_interaction: true,
248 });
249}
250
251getCLS(sendToGoogleAnalytics);
252getFID(sendToGoogleAnalytics);
253getLCP(sendToGoogleAnalytics);
254```
255
256### Send the results to Google Tag Manager
257
258The 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](https://github.com/GoogleChrome/web-vitals/pull/28#discussion_r422701126) for implementation details).
259
260```js
261import {getCLS, getFID, getLCP} from 'web-vitals';
262
263function sendToGTM({name, delta, id}) {
264 // Assumes the global `dataLayer` array exists, see:
265 // https://developers.google.com/tag-manager/devguide
266 dataLayer.push({
267 event: 'web-vitals',
268 event_category: 'Web Vitals',
269 event_action: name,
270 // Google Analytics metrics must be integers, so the value is rounded.
271 // For CLS the value is first multiplied by 1000 for greater precision
272 // (note: increase the multiplier for greater precision if needed).
273 event_value: Math.round(name === 'CLS' ? delta * 1000 : delta),
274 // The `id` value will be unique to the current page load. When sending
275 // multiple values from the same page (e.g. for CLS), Google Analytics can
276 // compute a total by grouping on this ID (note: requires `eventLabel` to
277 // be a dimension in your report).
278 event_label: id,
279 });
280}
281
282getCLS(sendToGTM);
283getFID(sendToGTM);
284getLCP(sendToGTM);
285```
286
287### Load `web-vitals` from a CDN
288
289The 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.
290
291The following examples show how to load `web-vitals` from [unpkg.com](https://unpkg.com), whether your targeting just modern browsers (using the "standard" version) or all browsers (using the "base+polyfill" version):
292
293**Load the "standard" version** (using a module script)
294
295```html
296<!-- Append the `?module` param to load the module version of `web-vitals` -->
297<script type="module">
298 import {getCLS, getFID, getLCP} from 'https://unpkg.com/web-vitals?module';
299
300 getCLS(console.log);
301 getFID(console.log);
302 getLCP(console.log);
303</script>
304```
305
306**Load the "standard" version** _(using a classic script)_
307
308```html
309<!-- Without the `?module` param, the UMD version is loaded and sets the `webVitals` global -->
310<script defer src="https://unpkg.com/web-vitals"></script>
311<script>
312addEventListener('DOMContentLoaded', function() {
313 webVitals.getCLS(console.log);
314 webVitals.getFID(console.log);
315 webVitals.getLCP(console.log);
316});
317</script>
318```
319
320**Load the "base+polyfill" version** _(using a classic script)_
321
322```html
323<!DOCTYPE html>
324<html>
325 <head>
326 <script>
327 // Inline code from `https://unpkg.com/web-vitals/dist/polyfill.js` here.
328 </script>
329 </head>
330 <body>
331 ...
332 <!-- Load the UMD version of the "base" bundle. -->
333 <script defer src="https://unpkg.com/web-vitals/dist/web-vitals.base.umd.js"></script>
334 <script>
335 addEventListener('DOMContentLoaded', function() {
336 webVitals.getCLS(console.log);
337 webVitals.getFID(console.log);
338 webVitals.getLCP(console.log);
339 });
340 </script>
341 </body>
342</html>
343```
344
345## Bundle versions
346
347The `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.
348
349The following table lists all the bundles distributed with the `web-vitals` package on npm.
350
351<table>
352 <tr>
353 <td width="35%">
354 <strong>Filename</strong> <em>(all within <code>dist/*</code>)</em>
355 </td>
356 <td><strong>Export</strong></td>
357 <td><strong>Description</strong></td>
358 </tr>
359 <tr>
360 <td><code>web-vitals.js</code></td>
361 <td><code>pkg.module</code></td>
362 <td>
363 <p>An ES module bundle of all metric functions, without any extra polyfills to expand browser support.</p>
364 This is the "standard" version and is the simplest way to consume this library out of the box.
365 </td>
366 </tr>
367 <tr>
368 <td><code>web-vitals.umd.js</code></td>
369 <td><code>pgk.main</code></td>
370 <td>
371 A UMD version of the <code>web-vitals.js</code> bundle (exposed on the <code>window.webVitals.*</code> namespace).
372 </td>
373 </tr>
374 <tr>
375 <td><code>web-vitals.base.js</code></td>
376 <td>--</td>
377 <td>
378 <p>An ES module bundle containing just the "base" part of the "base+polyfill" version.</p>
379 Use this bundle if (and only if) you've also added the <code>polyfill.js</code> script to the <code>&lt;head&gt;</code> of your pages. See <a href="#how-to-use-the-polyfill">how to use the polyfill</a> for more details.
380 </td>
381 </tr>
382 <tr>
383 <td><code>web-vitals.base.umd.js</code></td>
384 <td><code>--</code></td>
385 <td>
386 A UMD version of the <code>web-vitals.base.js</code> bundle (exposed on the <code>window.webVitals.*</code> namespace).
387 </td>
388 </tr>
389 <tr>
390 <td><code>polyfill.js</code></td>
391 <td>--</td>
392 <td>
393 <p>The "polyfill" part of the "base+polyfill" version. This script should be used with either <code>web-vitals.base.js</code> or <code>web-vitals.base.umd.js</code> (it will not work with the <code>web-vitals.js</code> or <code>web-vitals.umd.js</code> bundles).</p>
394 See <a href="#how-to-use-the-polyfill">how to use the polyfill</a> for more details.
395 </td>
396 </tr>
397</table>
398
399### Which bundle is right for you?
400
401Most 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.
402
403However, there are a few good reasons to consider using the "base+polyfill" version, for example:
404
405- FID can be measured in all browsers.
406- FCP, FID, and LCP will be more accurate in some cases (since the polyfill detects the page's initial `visibilityState` earlier).
407
408### How the polyfill works
409
410The `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).
411
412In 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.
413
414The "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.
415
416## API
417
418### Types:
419
420#### `Metric`
421
422```ts
423interface Metric {
424 // The name of the metric (in acronym form).
425 name: 'CLS' | 'FCP' | 'FID' | 'LCP' | 'TTFB';
426
427 // The current value of the metric.
428 value: number;
429
430 // The delta between the current value and the last-reported value.
431 // On the first report, `delta` and `value` will always be the same.
432 delta: number;
433
434 // A unique ID representing this particular metric that's specific to the
435 // current page. This ID can be used by an analytics tool to dedupe
436 // multiple values sent for the same metric, or to group multiple deltas
437 // together and calculate a total.
438 id: string;
439
440 // Any performance entries used in the metric value calculation.
441 // Note, entries will be added to the array as the value changes.
442 entries: (PerformanceEntry | FirstInputPolyfillEntry | NavigationTimingPolyfillEntry)[];
443}
444```
445
446#### `ReportHandler`
447
448```ts
449interface ReportHandler {
450 (metric: Metric): void;
451}
452```
453
454#### `FirstInputPolyfillEntry`
455
456When 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:
457
458```ts
459type FirstInputPolyfillEntry = Omit<PerformanceEventTiming,
460 'processingEnd' | 'processingEnd', 'toJSON'>
461```
462
463#### `FirstInputPolyfillCallback`
464
465```ts
466interface FirstInputPolyfillCallback {
467 (entry: FirstInputPolyfillEntry): void;
468}
469```
470
471#### `NavigationTimingPolyfillEntry`
472
473When calling `getTTFB()`, if the browser doesn't support the [Navigation Timing API Level 2](https://www.w3.org/TR/navigation-timing-2/) interface, it will polyfill the entry object using timings from `performance.timing`:
474
475```ts
476export type NavigationTimingPolyfillEntry = Omit<PerformanceNavigationTiming,
477 'initiatorType' | 'nextHopProtocol' | 'redirectCount' | 'transferSize' |
478 'encodedBodySize' | 'decodedBodySize' | 'toJSON'>
479```
480
481#### `WebVitalsGlobal`
482
483If using the "base+polyfill" build, the `polyfill.js` script creates the global `webVitals` namespace matching the following interface:
484
485```ts
486interface WebVitalsGlobal {
487 firstInputPolyfill: (onFirstInput: FirstInputPolyfillCallback) => void;
488 resetFirstInputPolyfill: () => void;
489 firstHiddenTime: number;
490}
491```
492
493### Functions:
494
495#### `getCLS()`
496
497```ts
498type getCLS = (onReport: ReportHandler, reportAllChanges?: boolean) => void
499```
500
501Calculates the [CLS](https://web.dev/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](https://heycam.github.io/webidl/#idl-double) (corresponding to a [layout shift value](https://wicg.github.io/layout-instability/#layout-shift-value)).
502
503If 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.
504
505_**Important:** unlike other metrics, CLS continues to monitor changes for the entire lifespan of the page&mdash;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](https://developers.google.com/web/updates/2018/07/page-lifecycle-api#advice-hidden), `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](#report-only-the-delta-of-changes) for how to manage this)._
506
507#### `getFCP()`
508
509```ts
510type getFCP = (onReport: ReportHandler, reportAllChanges?: boolean) => void
511```
512
513Calculates the [FCP](https://web.dev/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`.
514
515#### `getFID()`
516
517```ts
518type getFID = (onReport: ReportHandler, reportAllChanges?: boolean) => void
519```
520
521Calculates the [FID](https://web.dev/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](#fid-polyfill)). The reported value is a `DOMHighResTimeStamp`.
522
523_**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._
524
525#### `getLCP()`
526
527```ts
528type getLCP = (onReport: ReportHandler, reportAllChanges?: boolean) => void
529```
530
531Calculates the [LCP](https://web.dev/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`.
532
533If 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.
534
535#### `getTTFB()`
536
537```ts
538type getTTFB = (onReport: ReportHandler, reportAllChanges?: boolean) => void
539```
540
541Calculates the [TTFB](https://web.dev/time-to-first-byte/) 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`.
542
543Note, 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](https://w3c.github.io/navigation-timing/).
544
545For example, the TTFB metric starts from the page's [time origin](https://www.w3.org/TR/hr-time-2/#sec-time-origin), which means it [includes](https://developers.google.com/web/fundamentals/performance/navigation-and-resource-timing#the_life_and_timings_of_a_network_request) 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:
546
547```js
548import {getTTFB} from 'web-vitals';
549
550getTTFB((metric) => {
551 // Calculate the request time by subtracting from TTFB
552 // everything that happened prior to the request starting.
553 const requestTime = metric.value - metric.entries[0].requestStart;
554 console.log('Request time:', requestTime);
555});
556```
557
558_**Note:** browsers that do not support `navigation` entries will fall back to
559using `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._
560
561## Browser Support
562
563The `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).
564
565Browser support for each function is as follows:
566
567- `getCLS()`: Chromium,
568- `getFCP()`: Chromium, Safari Technology Preview
569- `getFID()`: Chromium, Firefox, Safari, Internet Explorer (with the [polyfill](#how-to-use-the-polyfill))
570- `getLCP()`: Chromium
571- `getTTFB()`: Chromium, Firefox, Safari, Internet Explorer
572
573## Limitations
574
575The `web-vitals` library is primarily a wrapper around the Web APIs that
576measure the Web Vitals metrics, which means the limitations of those APIs will
577mostly apply to this library as well.
578
579The 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).
580
581For 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.
582
583_**Note:** given the lack of iframe support, the `getCLS()` function technically measures [DCLS](https://github.com/wicg/layout-instability#cumulative-scores) (Document Cumulative Layout Shift) rather than CLS, if the page includes iframes)._
584
585## Development
586
587### Building the code
588
589The `web-vitals` source code is written in TypeScript. To transpile the code and build the production bundles, run the following command.
590
591```sh
592npm run build
593```
594
595To build the code and watch for changes, run:
596
597```sh
598npm run watch
599```
600
601### Running the tests
602
603The `web-vitals` code is tested in real browsers using [webdriver.io](https://webdriver.io/). Use the following command to run the tests:
604
605```sh
606npm test
607```
608
609To test any of the APIs manually, you can start the test server
610
611```sh
612npm run test:server
613```
614
615Then navigate to `http://localhost:9090/test/<view>`, where `<view>` is the basename of one the templates under [/test/views/](/test/views/).
616
617You'll likely want to combine this with `npm run watch` to ensure any changes you make are transpiled and rebuilt.
618
619## License
620
621[Apache 2.0](/LICENSE)