Merge pull request #237 from GoogleChrome/attribution

Add a new attribution build for debugging issues in the field

Author: philipwalton

README.md

@@ -0,0 +1,16 @@
+/*
+ Copyright 2022 Google LLC
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
+export * from './dist/modules/attribution.js';

attribution.d.ts

@@ -0,0 +1,18 @@
+/*
+ Copyright 2022 Google LLC
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
+// Creates the `web-vitals/attribution` import in node-based bundlers.
+// This will not be needed when export maps are widely supported.
+export * from './dist/web-vitals.attribution.js';

attribution.js

@@ -1 +1,16 @@
+/*
+ Copyright 2022 Google LLC
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
 export * from './dist/modules/index.js';

base.d.ts

@@ -1,3 +1,18 @@
+/*
+ Copyright 2022 Google LLC
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
 // Creates the `web-vitals/base` import in node-based bundlers.
 // This will not be needed when export maps are widely supported.
 export * from './dist/web-vitals.base.js';

base.js

@@ -2,10 +2,88 @@
   "name": "web-vitals",
   "version": "3.0.0-beta.2",
   "description": "Easily measure performance metrics in JavaScript",
+  "type": "module",
+  "typings": "dist/modules/index.d.ts",
   "main": "dist/web-vitals.umd.js",
   "module": "dist/web-vitals.js",
-  "typings": "dist/modules/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/modules/index.d.ts",
+      "require": "./dist/web-vitals.umd.js",
+      "default": "./dist/web-vitals.js"
+    },
+    "./base": {
+      "types": "./dist/modules/index.d.ts",
+      "require": "./dist/web-vitals.base.umd.js",
+      "default": "./dist/web-vitals.base.js"
+    },
+    "./base.js": {
+      "types": "./dist/modules/index.d.ts",
+      "require": "./dist/web-vitals.base.umd.js",
+      "default": "./dist/web-vitals.base.js"
+    },
+    "./attribution": {
+      "types": "./dist/modules/attribution.d.ts",
+      "require": "./dist/web-vitals.attribution.umd.js",
+      "default": "./dist/web-vitals.attribution.js"
+    },
+    "./attribution.js": {
+      "types": "./dist/modules/attribution.d.ts",
+      "require": "./dist/web-vitals.attribution.umd.js",
+      "default": "./dist/web-vitals.attribution.js"
+    },
+    "./onCLS.js": {
+      "types": "./dist/modules/onCLS.d.ts",
+      "default": "./dist/modules/onCLS.js"
+    },
+    "./onFCP.js": {
+      "types": "./dist/modules/onFCP.d.ts",
+      "default": "./dist/modules/onFCP.js"
+    },
+    "./onFID.js": {
+      "types": "./dist/modules/onFID.d.ts",
+      "default": "./dist/modules/onFID.js"
+    },
+    "./onINP.js": {
+      "types": "./dist/modules/onINP.d.ts",
+      "default": "./dist/modules/onINP.js"
+    },
+    "./onLCP.js": {
+      "types": "./dist/modules/onLCP.d.ts",
+      "default": "./dist/modules/onLCP.js"
+    },
+    "./onTTFB.js": {
+      "types": "./dist/modules/onTTFB.d.ts",
+      "default": "./dist/modules/onTTFB.js"
+    },
+    "./attribution/onCLS.js": {
+      "types": "./dist/modules/attribution/onCLS.d.ts",
+      "default": "./dist/modules/attribution/onCLS.js"
+    },
+    "./attribution/onFCP.js": {
+      "types": "./dist/modules/attribution/onFCP.d.ts",
+      "default": "./dist/modules/attribution/onFCP.js"
+    },
+    "./attribution/onFID.js": {
+      "types": "./dist/modules/attribution/onFID.d.ts",
+      "default": "./dist/modules/attribution/onFID.js"
+    },
+    "./attribution/onINP.js": {
+      "types": "./dist/modules/attribution/onINP.d.ts",
+      "default": "./dist/modules/attribution/onINP.js"
+    },
+    "./attribution/onLCP.js": {
+      "types": "./dist/modules/attribution/onLCP.d.ts",
+      "default": "./dist/modules/attribution/onLCP.js"
+    },
+    "./attribution/onTTFB.js": {
+      "types": "./dist/modules/attribution/onTTFB.d.ts",
+      "default": "./dist/modules/attribution/onTTFB.js"
+    }
+  },
   "files": [
+    "attribution.js",
+    "attribution.d.ts",
     "base.js",
     "base.d.ts",
     "dist",
@@ -24,7 +102,7 @@
     "release:minor": "npm version minor -m 'Release v%s' && npm publish",
     "release:patch": "npm version patch -m 'Release v%s' && npm publish",
     "test": "npm-run-all build -p -r test:*",
-    "test:e2e": "wdio wdio.conf.js",
+    "test:e2e": "wdio wdio.conf.cjs",
     "test:server": "node test/server.js",
     "start": "run-s build:ts test:server watch",
     "watch": "run-p watch:*",
@@ -37,9 +115,11 @@
     "crux",
     "performance",
     "metrics",
+    "Core Web Vitals",
     "CLS",
     "FCP",
     "FID",
+    "INP",
     "LCP",
     "TTFB"
   ],

package.json

@@ -105,6 +105,32 @@ const configs = [
     },
     plugins: configurePlugins({module: false}),
   },
+  {
+    input: 'dist/modules/attribution.js',
+    output: {
+      format: 'esm',
+      file: './dist/web-vitals.attribution.js',
+    },
+    plugins: configurePlugins({module: true, polyfill: false}),
+  },
+  {
+    input: 'dist/modules/attribution.js',
+    output: {
+      format: 'umd',
+      file: `./dist/web-vitals.attribution.umd.js`,
+      name: 'webVitals',
+    },
+    plugins: configurePlugins({module: false, polyfill: false}),
+  },
+  {
+    input: 'dist/modules/attribution.js',
+    output: {
+      format: 'iife',
+      file: './dist/web-vitals.attribution.iife.js',
+      name: 'webVitals',
+    },
+    plugins: configurePlugins({module: false, polyfill: false}),
+  },
 ];
 
 export default configs;

rollup.config.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export {onCLS} from './attribution/onCLS.js';
+export {onFCP} from './attribution/onFCP.js';
+export {onFID} from './attribution/onFID.js';
+export {onINP} from './attribution/onINP.js';
+export {onLCP} from './attribution/onLCP.js';
+export {onTTFB} from './attribution/onTTFB.js';
+
+export * from './types.js';

src/attribution.ts

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {getLoadState} from '../lib/getLoadState.js';
+import {getSelector} from '../lib/getSelector.js';
+import {onCLS as unattributedOnCLS} from '../onCLS.js';
+import {CLSAttribution, CLSReportCallback, CLSReportCallbackWithAttribution, CLSMetric, CLSMetricWithAttribution, ReportOpts} from '../types.js';
+
+
+const getLargestLayoutShiftEntry = (entries: LayoutShift[]) => {
+  return entries.reduce((a, b) => a && a.value > b.value ? a : b);
+}
+
+const getLargestLayoutShiftSource = (sources: LayoutShiftAttribution[]) => {
+  return sources.find((s) => s.node && s.node.nodeType === 1) || sources[0];
+}
+
+const attributeCLS = (metric: CLSMetric): CLSMetricWithAttribution => {
+  let attribution: CLSAttribution = {};
+  if (metric.entries.length) {
+    const largestEntry = getLargestLayoutShiftEntry(metric.entries);
+    if (largestEntry && largestEntry.sources && largestEntry.sources.length) {
+      const largestSource = getLargestLayoutShiftSource(largestEntry.sources);
+      if (largestSource) {
+        attribution = {
+          largestShiftTarget: getSelector(largestSource.node),
+          largestShiftTime: largestEntry.startTime,
+          largestShiftValue: largestEntry.value,
+          largestShiftSource: largestSource,
+          largestShiftEntry: largestEntry,
+          loadState: getLoadState(largestEntry.startTime),
+        };
+      }
+    }
+  }
+  return Object.assign(metric, {attribution});
+}
+
+/**
+ * Calculates the [CLS](https://web.dev/cls/) value for the current page and
+ * calls the `callback` 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 score](https://web.dev/cls/#layout-shift-score)).
+ *
+ * If the `reportAllChanges` configuration option is set to `true`, the
+ * `callback` function will be called as soon as the value is initially
+ * determined as well as any time the value changes throughout the page
+ * lifespan.
+ *
+ * _**Important:** CLS should be continually monitored for changes throughout
+ * the entire lifespan of a 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](https://developer.chrome.com/blog/page-lifecycle-api/#advice-hidden),
+ * `callback` is always called when the page's visibility state changes to
+ * hidden. As a result, the `callback` function might be called multiple times
+ * during the same page load._
+ */
+export const onCLS = (onReport: CLSReportCallbackWithAttribution, opts?: ReportOpts) => {
+  unattributedOnCLS(((metric: CLSMetric) => {
+    onReport(attributeCLS(metric));
+  }) as CLSReportCallback, opts);
+};

src/attribution/onCLS.ts

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {getBFCacheRestoreTime} from '../lib/bfcache.js';
+import {getLoadState} from '../lib/getLoadState.js';
+import {getNavigationEntry} from '../lib/getNavigationEntry.js';
+import {onFCP as unattributedOnFCP} from '../onFCP.js';
+import {FCPMetricWithAttribution, FCPReportCallback, FCPReportCallbackWithAttribution, ReportOpts} from '../types.js';
+
+
+const attributeFCP = (metric: FCPMetricWithAttribution): void => {
+  if (metric.entries.length) {
+    const navigationEntry = getNavigationEntry();
+    const fcpEntry = metric.entries[metric.entries.length - 1];
+
+    if (navigationEntry) {
+      const activationStart = navigationEntry.activationStart || 0;
+      const ttfb = Math.max(0, navigationEntry.responseStart - activationStart);
+
+      metric.attribution = {
+        timeToFirstByte: ttfb,
+        firstByteToFCP: metric.value - ttfb,
+        loadState: getLoadState(metric.entries[0].startTime),
+        navigationEntry,
+        fcpEntry,
+      };
+    }
+  } else {
+    // There are no entries when restored from bfcache.
+    metric.attribution = {
+      timeToFirstByte: 0,
+      firstByteToFCP: metric.value,
+      loadState: getLoadState(getBFCacheRestoreTime()),
+    };
+  }
+};
+
+/**
+ * Calculates the [FCP](https://web.dev/fcp/) value for the current page and
+ * calls the `callback` function once the value is ready, along with the
+ * relevant `paint` performance entry used to determine the value. The reported
+ * value is a `DOMHighResTimeStamp`.
+ */
+export const onFCP = (onReport: FCPReportCallbackWithAttribution, opts?: ReportOpts) => {
+  unattributedOnFCP(((metric: FCPMetricWithAttribution) => {
+    attributeFCP(metric);
+    onReport(metric);
+  }) as FCPReportCallback, opts);
+};