Bump web-vitals version (#1412)

From ~3 to ~4. Also make the metric interfaces optional in preparation for v5, which will remove the (deprecated in v4) `onFID` method.

The FID metric is already optional in the [schema](https://iglucentral.com/?q=web_vitals), so there should be no breaking change here when this metric becomes unavailable.

We assume if the user is using the library themselves they would be
manually loading it and telling us not to via:

- `loadVitalsScript: false`
- `webVitalsSource` override

So we don't consider this a breaking change unless a user is relying on us
to load v3 and with this update we start loading v4 (which has some
[breaking
changes](https://github.com/GoogleChrome/web-vitals/blob/main/docs/upgrading-to-v4.md)).
Users in this situation can set `webVitalsSource` to continue loading
v3.

When v5 is released, users can opt-in to using it by specifying
 a v5 source for `webVitalsSource`, which should work as expected with
 these changes until we update the plugin's default source to be v5.

Closes #1411

Author: jethron

common/changes/@snowplow/browser-plugin-web-vitals/feat-web-vitals-bump_2025-03-06-01-39.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-plugin-web-vitals",
+      "comment": "Update default external library version to v4. Add compatibility for future v5, which deprecates the FID metric.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-plugin-web-vitals"
+}

common/config/rush/pnpm-lock.yaml

@@ -1,5 +1,5 @@
 // DO NOT MODIFY THIS FILE MANUALLY BUT DO COMMIT IT. It is generated and used by Rush.
 {
-  "pnpmShrinkwrapHash": "6f4a24fea0d73ed30b10703fd10b02f67710f7ba",
+  "pnpmShrinkwrapHash": "483ab7c144cc1201cfba40405c05ebf190586e79",
   "preferredVersionsHash": "bf21a9e8fbc5a3846fb05b4fa0859e0917b2202f"
 }

common/config/rush/repo-state.json

@@ -25,7 +25,7 @@
     "@snowplow/browser-tracker-core": "workspace:*",
     "@snowplow/tracker-core": "workspace:*",
     "tslib": "^2.3.1",
-    "web-vitals": "~3.3.2"
+    "web-vitals": "~4.2.4"
   },
   "devDependencies": {
     "@ampproject/rollup-plugin-closure-compiler": "~0.27.0",

plugins/browser-plugin-web-vitals/package.json

@@ -4,7 +4,7 @@ import { WEB_VITALS_SCHEMA } from './schemata';
 import { attachWebVitalsPageListeners, createWebVitalsScript, webVitalsListener } from './utils';
 
 const _trackers: Record<string, BrowserTracker> = {};
-const WEB_VITALS_SOURCE = 'https://unpkg.com/web-vitals@3/dist/web-vitals.iife.js';
+const WEB_VITALS_SOURCE = 'https://unpkg.com/web-vitals@4/dist/web-vitals.iife.js';
 let listenersAttached = false;
 
 interface WebVitalsPluginOptions {

plugins/browser-plugin-web-vitals/src/index.ts

@@ -1,12 +1,18 @@
-import type { ReportCallback, Metric, WebVitalsGlobal, onCLS, onLCP, onFID, onFCP, onINP, onTTFB } from 'web-vitals';
+import type { MetricType, Metric, onCLS, onLCP, onFID, onFCP, onINP, onTTFB } from 'web-vitals';
 
-export interface WebVitals extends WebVitalsGlobal {
-  onCLS: typeof onCLS;
-  onFID: typeof onFID;
-  onLCP: typeof onLCP;
-  onFCP: typeof onFCP;
-  onINP: typeof onINP;
-  onTTFB: typeof onTTFB;
+export interface WebVitals {
+  onCLS?: typeof onCLS;
+  onFID?: typeof onFID;
+  onLCP?: typeof onLCP;
+  onFCP?: typeof onFCP;
+  onINP?: typeof onINP;
+  onTTFB?: typeof onTTFB;
 }
 
-export { Metric, ReportCallback };
+declare global {
+  interface Window {
+    webVitals?: WebVitals;
+  }
+}
+
+export { Metric, MetricType };

plugins/browser-plugin-web-vitals/src/types.ts

@@ -1,5 +1,5 @@
 import { LOG } from '@snowplow/tracker-core';
-import { ReportCallback, WebVitals } from './types';
+import { MetricType } from './types';
 
 /**
  * Attach page listeners to collect the Web Vitals values
@@ -51,22 +51,23 @@ export function createWebVitalsScript(webVitalsSource: string) {
  * @return {void}
  */
 export function webVitalsListener(webVitalsObject: Record<string, unknown>) {
-  function addWebVitalsMeasurement(metricSchemaName: string): ReportCallback {
+  function addWebVitalsMeasurement(metricSchemaName: string): (arg: MetricType) => void {
     return (arg) => {
       webVitalsObject[metricSchemaName] = arg.value;
       webVitalsObject.navigationType = arg.navigationType;
     };
   }
-  if (!window.webVitals) {
+
+  const webVitals = window.webVitals;
+  if (!webVitals) {
     LOG.warn('The window.webVitals API is currently unavailable. web_vitals events will not be collected.');
     return;
   }
 
-  const webVitals = window.webVitals as WebVitals;
-  webVitals.onCLS(addWebVitalsMeasurement('cls'));
-  webVitals.onFID(addWebVitalsMeasurement('fid'));
-  webVitals.onLCP(addWebVitalsMeasurement('lcp'));
-  webVitals.onFCP(addWebVitalsMeasurement('fcp'));
-  webVitals.onINP(addWebVitalsMeasurement('inp'));
-  webVitals.onTTFB(addWebVitalsMeasurement('ttfb'));
+  webVitals.onCLS?.(addWebVitalsMeasurement('cls'));
+  webVitals.onFID?.(addWebVitalsMeasurement('fid'));
+  webVitals.onLCP?.(addWebVitalsMeasurement('lcp'));
+  webVitals.onFCP?.(addWebVitalsMeasurement('fcp'));
+  webVitals.onINP?.(addWebVitalsMeasurement('inp'));
+  webVitals.onTTFB?.(addWebVitalsMeasurement('ttfb'));
 }

plugins/browser-plugin-web-vitals/src/utils.ts

@@ -5,7 +5,6 @@ import { BrowserTracker } from '@snowplow/browser-tracker-core';
 
 declare var jsdom: JSDOM;
 
-// @ts-expect-error
 jsdom.window.webVitals = {};
 
 describe('Web Vitals plugin', () => {