UNPKG

30.5 kBMarkdownView Raw
1# `web-vitals`
2
3- [Overview](#overview)
4- [Install and load the library](#installation)
5 - [From npm](#import-web-vitals-from-npm)
6 - [From a CDN](#load-web-vitals-from-a-cdn)
7- [Usage](#usage)
8 - [Basic usage](#basic-usage)
9 - [Report the value on every change](#report-the-value-on-every-change)
10 - [Report only the delta of changes](#report-only-the-delta-of-changes)
11 - [Send the results to an analytics endpoint](#send-the-results-to-an-analytics-endpoint)
12 - [Send the results to Google Analytics](#send-the-results-to-google-analytics)
13 - [Send the results to Google Tag Manager](#send-the-results-to-google-tag-manager)
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<a name="installation"><a>
43<a name="load-the-library"><a>
44
45## Install and load the library
46
47<a name="import-web-vitals-from-npm"><a>
48
49### From npm
50
51You can install this library from npm by running:
52
53```sh
54npm install web-vitals
55```
56
57_**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._
58
59There 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.
60
61For details on the difference between the two versions, see <a href="#which-bundle-is-right-for-you">which bundle is right for you</a>.
62
63**1. The "standard" version**
64
65To 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):
66
67```js
68import {getLCP, getFID, getCLS} from 'web-vitals';
69
70getCLS(console.log);
71getFID(console.log);
72getLCP(console.log);
73```
74
75<a name="how-to-use-the-polyfill"><a>
76
77**2. The "base+polyfill" version**
78
79Loading the "base+polyfill" version is a two-step process:
80
81First, 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`:
82
83```diff
84- import {getLCP, getFID, getCLS} from 'web-vitals';
85+ import {getLCP, getFID, getCLS} from 'web-vitals/base';
86```
87
88Then, inline the code from `dist/polyfill.js` into the `<head>` of your pages. This step is important since the "base" build will error if the polyfill code has not been added.
89
90```html
91<!DOCTYPE html>
92<html>
93 <head>
94 <script>
95 // Inline code from `dist/polyfill.js` here
96 </script>
97 </head>
98 <body>
99 ...
100 </body>
101</html>
102```
103
104Note 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.
105
106_**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._
107
108<a name="load-web-vitals-from-a-cdn"><a>
109
110### From a CDN
111
112The 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.
113
114The following examples show how to load `web-vitals` from [unpkg.com](https://unpkg.com), whether your targeting just Chromium-based browsers (using the "standard" version) or additional browsers (using the "base+polyfill" version):
115
116**Load the "standard" version** _(using a module script)_
117
118```html
119<!-- Append the `?module` param to load the module version of `web-vitals` -->
120<script type="module">
121 import {getCLS, getFID, getLCP} from 'https://unpkg.com/web-vitals?module';
122
123 getCLS(console.log);
124 getFID(console.log);
125 getLCP(console.log);
126</script>
127```
128
129**Load the "standard" version** _(using a classic script)_
130
131```html
132<script>
133(function() {
134 var script = document.createElement('script');
135 script.src = 'https://unpkg.com/web-vitals/dist/web-vitals.iife.js';
136 script.onload = function() {
137 // When loading `web-vitals` using a classic script, all the public
138 // methods can be found on the `webVitals` global namespace.
139 webVitals.getCLS(console.log);
140 webVitals.getFID(console.log);
141 webVitals.getLCP(console.log);
142 }
143 document.head.appendChild(script);
144}())
145</script>
146```
147
148**Load the "base+polyfill" version** _(using a classic script)_
149
150```html
151<!DOCTYPE html>
152<html>
153 <head>
154 <script>
155 // Inline code from `https://unpkg.com/web-vitals/dist/polyfill.js` here.
156 </script>
157 </head>
158 <body>
159 ...
160 <!-- Load the UMD version of the "base" bundle. -->
161 <script>
162 (function() {
163 var script = document.createElement('script');
164 script.src = 'https://unpkg.com/web-vitals/dist/web-vitals.iife.js';
165 script.onload = function() {
166 // When loading `web-vitals` using a classic script, all the public
167 // methods can be found on the `webVitals` global namespace.
168 webVitals.getCLS(console.log);
169 webVitals.getFID(console.log);
170 webVitals.getLCP(console.log);
171 }
172 document.head.appendChild(script);
173 }())
174 </script>
175 </body>
176</html>
177```
178
179## Usage
180
181### Basic usage
182
183Each 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.
184
185The following example measures each of the Core Web Vitals metrics and logs the result to the console once its value is ready to report.
186
187_(The examples below import the "standard" version, but they will work with the polyfill version as well.)_
188
189```js
190import {getCLS, getFID, getLCP} from 'web-vitals';
191
192getCLS(console.log);
193getFID(console.log);
194getLCP(console.log);
195```
196
197Note 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.
198
199Also, in some cases a metric callback may never be called:
200
201- FID is not reported if the user never interacts with the page.
202- FCP, FID, and LCP are not reported if the page was loaded in the background.
203
204In other cases, a metric callback may be called more than once:
205
206- 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).
207- CLS, FCP, FID, and LCP are reported again after a page is restored from the [back/forward cache](https://web.dev/bfcache/).
208
209_**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._
210
211### Report the value on every change
212
213In 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`.
214
215This can be useful when debugging, but in general using `reportAllChanges` is not needed (or recommended).
216
217```js
218import {getCLS} from 'web-vitals';
219
220// Logs CLS as the value changes.
221getCLS(console.log, true);
222```
223
224### Report only the delta of changes
225
226Some 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`).
227
228Other 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.
229
230The following example shows how to use the `id` and `delta` properties:
231
232```js
233import {getCLS, getFID, getLCP} from 'web-vitals';
234
235function logDelta({name, id, delta}) {
236 console.log(`${name} matching ID ${id} changed by ${delta}`);
237}
238
239getCLS(logDelta);
240getFID(logDelta);
241getLCP(logDelta);
242```
243
244_**Note:** the first time the `onReport` function is called, its `value` and `delta` properties will be the same._
245
246In 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).
247
248### Send the results to an analytics endpoint
249
250The 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.
251
252The `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.
253
254```js
255import {getCLS, getFID, getLCP} from 'web-vitals';
256
257function sendToAnalytics(metric) {
258 const body = JSON.stringify({[metric.name]: metric.value});
259 // Use `navigator.sendBeacon()` if available, falling back to `fetch()`.
260 (navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
261 fetch('/analytics', {body, method: 'POST', keepalive: true});
262}
263
264getCLS(sendToAnalytics);
265getFID(sendToAnalytics);
266getLCP(sendToAnalytics);
267```
268
269### Send the results to Google Analytics
270
271Google 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](https://developers.google.com/analytics/devguides/reporting) and any data visualization library you choose.
272
273As an example of this, the [Web Vitals Report](https://github.com/GoogleChromeLabs/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.
274
275[![web-vitals-report](https://user-images.githubusercontent.com/326742/101584324-3f9a0900-3992-11eb-8f2d-182f302fb67b.png)](https://github.com/GoogleChromeLabs/web-vitals-report)
276
277In order to use the [Web Vitals Report](https://github.com/GoogleChromeLabs/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:
278
279#### Using `analytics.js`
280
281```js
282import {getCLS, getFID, getLCP} from 'web-vitals';
283
284function sendToGoogleAnalytics({name, delta, id}) {
285 // Assumes the global `ga()` function exists, see:
286 // https://developers.google.com/analytics/devguides/collection/analyticsjs
287 ga('send', 'event', {
288 eventCategory: 'Web Vitals',
289 eventAction: name,
290 // The `id` value will be unique to the current page load. When sending
291 // multiple values from the same page (e.g. for CLS), Google Analytics can
292 // compute a total by grouping on this ID (note: requires `eventLabel` to
293 // be a dimension in your report).
294 eventLabel: id,
295 // Google Analytics metrics must be integers, so the value is rounded.
296 // For CLS the value is first multiplied by 1000 for greater precision
297 // (note: increase the multiplier for greater precision if needed).
298 eventValue: Math.round(name === 'CLS' ? delta * 1000 : delta),
299 // Use a non-interaction event to avoid affecting bounce rate.
300 nonInteraction: true,
301 // Use `sendBeacon()` if the browser supports it.
302 transport: 'beacon',
303
304 // OPTIONAL: any additional params or debug info here.
305 // See: https://web.dev/debug-web-vitals-in-the-field/
306 // dimension1: '...',
307 // dimension2: '...',
308 // ...
309 });
310}
311
312getCLS(sendToGoogleAnalytics);
313getFID(sendToGoogleAnalytics);
314getLCP(sendToGoogleAnalytics);
315```
316
317#### Using `gtag.js` (Universal Analytics)
318
319```js
320import {getCLS, getFID, getLCP} from 'web-vitals';
321
322function sendToGoogleAnalytics({name, delta, id}) {
323 // Assumes the global `gtag()` function exists, see:
324 // https://developers.google.com/analytics/devguides/collection/gtagjs
325 gtag('event', name, {
326 event_category: 'Web Vitals',
327 // The `id` value will be unique to the current page load. When sending
328 // multiple values from the same page (e.g. for CLS), Google Analytics can
329 // compute a total by grouping on this ID (note: requires `eventLabel` to
330 // be a dimension in your report).
331 event_label: id,
332 // Google Analytics metrics must be integers, so the value is rounded.
333 // For CLS the value is first multiplied by 1000 for greater precision
334 // (note: increase the multiplier for greater precision if needed).
335 value: Math.round(name === 'CLS' ? delta * 1000 : delta),
336 // Use a non-interaction event to avoid affecting bounce rate.
337 non_interaction: true,
338
339 // OPTIONAL: any additional params or debug info here.
340 // See: https://web.dev/debug-web-vitals-in-the-field/
341 // metric_rating: 'good' | 'ni' | 'poor',
342 // debug_info: '...',
343 // ...
344 });
345}
346
347getCLS(sendToGoogleAnalytics);
348getFID(sendToGoogleAnalytics);
349getLCP(sendToGoogleAnalytics);
350```
351
352#### Using `gtag.js` (Google Analytics 4)
353
354[Google Analytics 4](https://support.google.com/analytics/answer/10089681) introduces a new Event model allowing custom parameters instead of a fixed category, action, and label. It also supports non-integer values, making it easier to measure Web Vitals metrics compared to previous versions.
355
356```js
357import {getCLS, getFID, getLCP} from 'web-vitals';
358
359function sendToGoogleAnalytics({name, delta, value, id}) {
360 // Assumes the global `gtag()` function exists, see:
361 // https://developers.google.com/analytics/devguides/collection/ga4
362 gtag('event', name, {
363 // Built-in params:
364 value: delta, // Use `delta` so the value can be summed.
365 // Custom params:
366 metric_id: id, // Needed to aggregate events.
367 metric_value: value, // Optional.
368 metric_delta: delta, // Optional.
369
370 // OPTIONAL: any additional params or debug info here.
371 // See: https://web.dev/debug-web-vitals-in-the-field/
372 // metric_rating: 'good' | 'ni' | 'poor',
373 // debug_info: '...',
374 // ...
375 });
376}
377
378getCLS(sendToGoogleAnalytics);
379getFID(sendToGoogleAnalytics);
380getLCP(sendToGoogleAnalytics);
381```
382
383### Send the results to Google Tag Manager
384
385The recommended way to measure Web Vitals metrics with Google Tag Manager is using the [Core Web Vitals](https://www.simoahava.com/custom-templates/core-web-vitals/) custom template tag created and maintained by [Simo Ahava](https://www.simoahava.com/).
386
387For full installation and usage instructions, see Simo's post: [Track Core Web Vitals in GA4 with Google Tag Manager](https://www.simoahava.com/analytics/track-core-web-vitals-in-ga4-with-google-tag-manager/).
388
389## Bundle versions
390
391The `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.
392
393The following table lists all the bundles distributed with the `web-vitals` package on npm.
394
395<table>
396 <tr>
397 <td width="35%">
398 <strong>Filename</strong> <em>(all within <code>dist/*</code>)</em>
399 </td>
400 <td><strong>Export</strong></td>
401 <td><strong>Description</strong></td>
402 </tr>
403 <tr>
404 <td><code>web-vitals.js</code></td>
405 <td><code>pkg.module</code></td>
406 <td>
407 <p>An ES module bundle of all metric functions, without any extra polyfills to expand browser support.</p>
408 This is the "standard" version and is the simplest way to consume this library out of the box.
409 </td>
410 </tr>
411 <tr>
412 <td><code>web-vitals.umd.js</code></td>
413 <td><code>pgk.main</code></td>
414 <td>
415 A UMD version of the <code>web-vitals.js</code> bundle (exposed on the <code>window.webVitals.*</code> namespace).
416 </td>
417 </tr>
418 <tr>
419 <td><code>web-vitals.base.js</code></td>
420 <td>--</td>
421 <td>
422 <p>An ES module bundle containing just the "base" part of the "base+polyfill" version.</p>
423 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.
424 </td>
425 </tr>
426 <tr>
427 <td><code>web-vitals.base.umd.js</code></td>
428 <td><code>--</code></td>
429 <td>
430 A UMD version of the <code>web-vitals.base.js</code> bundle (exposed on the <code>window.webVitals.*</code> namespace).
431 </td>
432 </tr>
433 <tr>
434 <td><code>polyfill.js</code></td>
435 <td>--</td>
436 <td>
437 <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>
438 See <a href="#how-to-use-the-polyfill">how to use the polyfill</a> for more details.
439 </td>
440 </tr>
441</table>
442
443### Which bundle is right for you?
444
445Most 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.
446
447However, there are a few good reasons to consider using the "base+polyfill" version, for example:
448
449- FID can be measured in all browsers.
450- CLS, FCP, FID, and LCP will be more accurate in some cases (since the polyfill detects the page's initial `visibilityState` earlier).
451
452### How the polyfill works
453
454The `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 CLS, FCP, LCP, and FID).
455
456In 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.
457
458The "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.
459
460## API
461
462### Types:
463
464#### `Metric`
465
466```ts
467interface Metric {
468 // The name of the metric (in acronym form).
469 name: 'CLS' | 'FCP' | 'FID' | 'LCP' | 'TTFB';
470
471 // The current value of the metric.
472 value: number;
473
474 // The delta between the current value and the last-reported value.
475 // On the first report, `delta` and `value` will always be the same.
476 delta: number;
477
478 // A unique ID representing this particular metric that's specific to the
479 // current page. This ID can be used by an analytics tool to dedupe
480 // multiple values sent for the same metric, or to group multiple deltas
481 // together and calculate a total.
482 id: string;
483
484 // Any performance entries used in the metric value calculation.
485 // Note, entries will be added to the array as the value changes.
486 entries: (PerformanceEntry | FirstInputPolyfillEntry | NavigationTimingPolyfillEntry)[];
487}
488```
489
490#### `ReportHandler`
491
492```ts
493interface ReportHandler {
494 (metric: Metric): void;
495}
496```
497
498#### `FirstInputPolyfillEntry`
499
500When 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:
501
502```ts
503type FirstInputPolyfillEntry = Omit<PerformanceEventTiming,
504 'processingEnd' | 'processingEnd', 'toJSON'>
505```
506
507#### `FirstInputPolyfillCallback`
508
509```ts
510interface FirstInputPolyfillCallback {
511 (entry: FirstInputPolyfillEntry): void;
512}
513```
514
515#### `NavigationTimingPolyfillEntry`
516
517When 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`:
518
519```ts
520export type NavigationTimingPolyfillEntry = Omit<PerformanceNavigationTiming,
521 'initiatorType' | 'nextHopProtocol' | 'redirectCount' | 'transferSize' |
522 'encodedBodySize' | 'decodedBodySize' | 'toJSON'>
523```
524
525#### `WebVitalsGlobal`
526
527If using the "base+polyfill" build, the `polyfill.js` script creates the global `webVitals` namespace matching the following interface:
528
529```ts
530interface WebVitalsGlobal {
531 firstInputPolyfill: (onFirstInput: FirstInputPolyfillCallback) => void;
532 resetFirstInputPolyfill: () => void;
533 firstHiddenTime: number;
534}
535```
536
537### Functions:
538
539#### `getCLS()`
540
541```ts
542type getCLS = (onReport: ReportHandler, reportAllChanges?: boolean) => void
543```
544
545Calculates 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 score](https://web.dev/cls/#layout-shift-score)).
546
547If 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.
548
549_**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)._
550
551#### `getFCP()`
552
553```ts
554type getFCP = (onReport: ReportHandler, reportAllChanges?: boolean) => void
555```
556
557Calculates 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`](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp).
558
559#### `getFID()`
560
561```ts
562type getFID = (onReport: ReportHandler, reportAllChanges?: boolean) => void
563```
564
565Calculates 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`](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp).
566
567_**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._
568
569#### `getLCP()`
570
571```ts
572type getLCP = (onReport: ReportHandler, reportAllChanges?: boolean) => void
573```
574
575Calculates 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`](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp).
576
577If 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.
578
579#### `getTTFB()`
580
581```ts
582type getTTFB = (onReport: ReportHandler, reportAllChanges?: boolean) => void
583```
584
585Calculates 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`](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp).
586
587Note, 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/).
588
589For 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:
590
591```js
592import {getTTFB} from 'web-vitals';
593
594getTTFB((metric) => {
595 // Calculate the request time by subtracting from TTFB
596 // everything that happened prior to the request starting.
597 const requestTime = metric.value - metric.entries[0].requestStart;
598 console.log('Request time:', requestTime);
599});
600```
601
602_**Note:** browsers that do not support `navigation` entries will fall back to
603using `performance.timing` (with the timestamps converted from epoch time to [`DOMHighResTimeStamp`](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp)). This ensures code referencing these values (like in the example above) will work the same in all browsers._
604
605## Browser Support
606
607The `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).
608
609Browser support for each function is as follows:
610
611- `getCLS()`: Chromium,
612- `getFCP()`: Chromium, Firefox, Safari
613- `getFID()`: Chromium, Firefox, Safari, Internet Explorer (with the [polyfill](#how-to-use-the-polyfill))
614- `getLCP()`: Chromium
615- `getTTFB()`: Chromium, Firefox, Safari, Internet Explorer
616
617## Limitations
618
619The `web-vitals` library is primarily a wrapper around the Web APIs that
620measure the Web Vitals metrics, which means the limitations of those APIs will
621mostly apply to this library as well.
622
623The 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).
624
625For 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.
626
627_**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)._
628
629## Development
630
631### Building the code
632
633The `web-vitals` source code is written in TypeScript. To transpile the code and build the production bundles, run the following command.
634
635```sh
636npm run build
637```
638
639To build the code and watch for changes, run:
640
641```sh
642npm run watch
643```
644
645### Running the tests
646
647The `web-vitals` code is tested in real browsers using [webdriver.io](https://webdriver.io/). Use the following command to run the tests:
648
649```sh
650npm test
651```
652
653To test any of the APIs manually, you can start the test server
654
655```sh
656npm run test:server
657```
658
659Then navigate to `http://localhost:9090/test/<view>`, where `<view>` is the basename of one the templates under [/test/views/](/test/views/).
660
661You'll likely want to combine this with `npm run watch` to ensure any changes you make are transpiled and rebuilt.
662
663## License
664
665[Apache 2.0](/LICENSE)