@codeserk/forge-stats-web-vitals 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codeserk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @codeserk/forge-stats-web-vitals
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Web vitals plugin for [`@codeserk/forge-stats`](../stats/README.md). It re-exports the whole core client, so a web app imports this package alone. The core is a peer dependency, installed with it by npm 7+, so the app always has a single client.
+
+## Installation
+
+```bash
+npm install @codeserk/forge-stats-web-vitals
+```
+
+## Usage
+
+Captures LCP, INP, CLS, FCP and TTFB with `web-vitals`, plus the DOMContentLoaded (`domLoad`) and load (`pageLoad`) times, and tracks them as one `Performance` event per page load when the page is first hidden. `getRoute` returns the route pattern, not the raw pathname. A metric that did not happen is left out:
+
+```ts
+import { init, webVitals } from '@codeserk/forge-stats-web-vitals'
+
+init({ sdk: 'YOUR_SDK_KEY', plugins: [webVitals({ getRoute: () => router.currentRoute.pattern })] })
+```

package/dist/index.cjs

@@ -0,0 +1,72 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let web_vitals = require("web-vitals");
+//#region src/web-vitals.const.ts
+const PERFORMANCE_EVENT_TYPE = "Performance";
+const WEB_VITALS_PLUGIN_NAME = "web-vitals";
+//#endregion
+//#region src/web-vitals.ts
+/**
+* Returns the plugin that tracks the web vitals of the page load as one `Performance` event.
+* @param options
+* @returns the plugin for `init`
+*/
+function webVitals(options) {
+	return {
+		name: WEB_VITALS_PLUGIN_NAME,
+		setup: (client) => captureWebVitals(client, options)
+	};
+}
+/**
+* Tracks the web vitals through the client the first time the page is hidden, when INP and CLS are final.
+* @param client
+* @param options
+*/
+function captureWebVitals(client, { getRoute }) {
+	const metrics = {};
+	const collect = (metric) => {
+		metrics[metric.name.toLowerCase()] = metric.value;
+	};
+	(0, web_vitals.onLCP)(collect);
+	(0, web_vitals.onINP)(collect);
+	(0, web_vitals.onCLS)(collect);
+	(0, web_vitals.onFCP)(collect);
+	(0, web_vitals.onTTFB)(collect);
+	const onVisibilityChange = () => {
+		if (document.visibilityState !== "hidden") return;
+		document.removeEventListener("visibilitychange", onVisibilityChange);
+		client.track({
+			type: PERFORMANCE_EVENT_TYPE,
+			name: getRoute(),
+			data: {
+				context: "web",
+				...metrics,
+				...loadTimes()
+			}
+		});
+	};
+	document.addEventListener("visibilitychange", onVisibilityChange);
+}
+/**
+* Returns the DOMContentLoaded and load times reached so far.
+* @returns the times in ms, as `domLoad` and `pageLoad`
+*/
+function loadTimes() {
+	const [navigation] = performance.getEntriesByType("navigation");
+	const times = {};
+	if (navigation?.domContentLoadedEventEnd > 0) times.domLoad = navigation.domContentLoadedEventEnd;
+	if (navigation?.loadEventEnd > 0) times.pageLoad = navigation.loadEventEnd;
+	return times;
+}
+//#endregion
+exports.webVitals = webVitals;
+var _codeserk_forge_stats = require("@codeserk/forge-stats");
+Object.keys(_codeserk_forge_stats).forEach(function(k) {
+	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function() {
+			return _codeserk_forge_stats[k];
+		}
+	});
+});
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/web-vitals.const.ts","../src/web-vitals.ts"],"sourcesContent":["export const PERFORMANCE_EVENT_TYPE = 'Performance'\nexport const WEB_CONTEXT = 'web'\nexport const WEB_VITALS_PLUGIN_NAME = 'web-vitals'\n","import type { Client, StatsPlugin } from '@codeserk/forge-stats'\nimport { type Metric, onCLS, onFCP, onINP, onLCP, onTTFB } from 'web-vitals'\n\nimport { PERFORMANCE_EVENT_TYPE, WEB_CONTEXT, WEB_VITALS_PLUGIN_NAME } from './web-vitals.const'\nimport type { WebVitalsOptions } from './web-vitals.types'\n\n/**\n * Returns the plugin that tracks the web vitals of the page load as one `Performance` event.\n * @param options\n * @returns the plugin for `init`\n */\nexport function webVitals(options: WebVitalsOptions): StatsPlugin {\n  return {\n    name: WEB_VITALS_PLUGIN_NAME,\n    setup: (client) => captureWebVitals(client, options),\n  }\n}\n\n/**\n * Tracks the web vitals through the client the first time the page is hidden, when INP and CLS are final.\n * @param client\n * @param options\n */\nfunction captureWebVitals(client: Client, { getRoute }: WebVitalsOptions): void {\n  const metrics: Record<string, number> = {}\n  const collect = (metric: Metric) => {\n    metrics[metric.name.toLowerCase()] = metric.value\n  }\n  onLCP(collect)\n  onINP(collect)\n  onCLS(collect)\n  onFCP(collect)\n  onTTFB(collect)\n\n  const onVisibilityChange = () => {\n    if (document.visibilityState !== 'hidden') {\n      return\n    }\n\n    document.removeEventListener('visibilitychange', onVisibilityChange)\n    client.track({\n      type: PERFORMANCE_EVENT_TYPE,\n      name: getRoute(),\n      data: { context: WEB_CONTEXT, ...metrics, ...loadTimes() },\n    })\n  }\n  document.addEventListener('visibilitychange', onVisibilityChange)\n}\n\n/**\n * Returns the DOMContentLoaded and load times reached so far.\n * @returns the times in ms, as `domLoad` and `pageLoad`\n */\nfunction loadTimes(): Record<string, number> {\n  const [navigation] = performance.getEntriesByType('navigation') as PerformanceNavigationTiming[]\n  const times: Record<string, number> = {}\n  if (navigation?.domContentLoadedEventEnd > 0) {\n    times.domLoad = navigation.domContentLoadedEventEnd\n  }\n  if (navigation?.loadEventEnd > 0) {\n    times.pageLoad = navigation.loadEventEnd\n  }\n\n  return times\n}\n"],"mappings":";;;AAAA,MAAa,yBAAyB;AAEtC,MAAa,yBAAyB;;;;;;;;ACStC,SAAgB,UAAU,SAAwC;AAChE,QAAO;EACL,MAAM;EACN,QAAQ,WAAW,iBAAiB,QAAQ,QAAQ;EACrD;;;;;;;AAQH,SAAS,iBAAiB,QAAgB,EAAE,YAAoC;CAC9E,MAAM,UAAkC,EAAE;CAC1C,MAAM,WAAW,WAAmB;AAClC,UAAQ,OAAO,KAAK,aAAa,IAAI,OAAO;;AAE9C,EAAA,GAAA,WAAA,OAAM,QAAQ;AACd,EAAA,GAAA,WAAA,OAAM,QAAQ;AACd,EAAA,GAAA,WAAA,OAAM,QAAQ;AACd,EAAA,GAAA,WAAA,OAAM,QAAQ;AACd,EAAA,GAAA,WAAA,QAAO,QAAQ;CAEf,MAAM,2BAA2B;AAC/B,MAAI,SAAS,oBAAoB,SAC/B;AAGF,WAAS,oBAAoB,oBAAoB,mBAAmB;AACpE,SAAO,MAAM;GACX,MAAM;GACN,MAAM,UAAU;GAChB,MAAM;IAAE,SAAA;IAAsB,GAAG;IAAS,GAAG,WAAW;IAAE;GAC3D,CAAC;;AAEJ,UAAS,iBAAiB,oBAAoB,mBAAmB;;;;;;AAOnE,SAAS,YAAoC;CAC3C,MAAM,CAAC,cAAc,YAAY,iBAAiB,aAAa;CAC/D,MAAM,QAAgC,EAAE;AACxC,KAAI,YAAY,2BAA2B,EACzC,OAAM,UAAU,WAAW;AAE7B,KAAI,YAAY,eAAe,EAC7B,OAAM,WAAW,WAAW;AAG9B,QAAO"}

package/dist/index.d.cts

@@ -0,0 +1,19 @@
+import { StatsPlugin } from "@codeserk/forge-stats";
+export * from "@codeserk/forge-stats";
+
+//#region src/web-vitals.types.d.ts
+interface WebVitalsOptions {
+  /** Returns the route pattern, not the raw pathname. @example '/products/:id' */
+  readonly getRoute: () => string;
+}
+//#endregion
+//#region src/web-vitals.d.ts
+/**
+ * Returns the plugin that tracks the web vitals of the page load as one `Performance` event.
+ * @param options
+ * @returns the plugin for `init`
+ */
+declare function webVitals(options: WebVitalsOptions): StatsPlugin;
+//#endregion
+export { type WebVitalsOptions, webVitals };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+import { StatsPlugin } from "@codeserk/forge-stats";
+export * from "@codeserk/forge-stats";
+
+//#region src/web-vitals.types.d.ts
+interface WebVitalsOptions {
+  /** Returns the route pattern, not the raw pathname. @example '/products/:id' */
+  readonly getRoute: () => string;
+}
+//#endregion
+//#region src/web-vitals.d.ts
+/**
+ * Returns the plugin that tracks the web vitals of the page load as one `Performance` event.
+ * @param options
+ * @returns the plugin for `init`
+ */
+declare function webVitals(options: WebVitalsOptions): StatsPlugin;
+//#endregion
+export { type WebVitalsOptions, webVitals };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,63 @@
+import { onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals";
+export * from "@codeserk/forge-stats";
+//#region src/web-vitals.const.ts
+const PERFORMANCE_EVENT_TYPE = "Performance";
+const WEB_VITALS_PLUGIN_NAME = "web-vitals";
+//#endregion
+//#region src/web-vitals.ts
+/**
+* Returns the plugin that tracks the web vitals of the page load as one `Performance` event.
+* @param options
+* @returns the plugin for `init`
+*/
+function webVitals(options) {
+	return {
+		name: WEB_VITALS_PLUGIN_NAME,
+		setup: (client) => captureWebVitals(client, options)
+	};
+}
+/**
+* Tracks the web vitals through the client the first time the page is hidden, when INP and CLS are final.
+* @param client
+* @param options
+*/
+function captureWebVitals(client, { getRoute }) {
+	const metrics = {};
+	const collect = (metric) => {
+		metrics[metric.name.toLowerCase()] = metric.value;
+	};
+	onLCP(collect);
+	onINP(collect);
+	onCLS(collect);
+	onFCP(collect);
+	onTTFB(collect);
+	const onVisibilityChange = () => {
+		if (document.visibilityState !== "hidden") return;
+		document.removeEventListener("visibilitychange", onVisibilityChange);
+		client.track({
+			type: PERFORMANCE_EVENT_TYPE,
+			name: getRoute(),
+			data: {
+				context: "web",
+				...metrics,
+				...loadTimes()
+			}
+		});
+	};
+	document.addEventListener("visibilitychange", onVisibilityChange);
+}
+/**
+* Returns the DOMContentLoaded and load times reached so far.
+* @returns the times in ms, as `domLoad` and `pageLoad`
+*/
+function loadTimes() {
+	const [navigation] = performance.getEntriesByType("navigation");
+	const times = {};
+	if (navigation?.domContentLoadedEventEnd > 0) times.domLoad = navigation.domContentLoadedEventEnd;
+	if (navigation?.loadEventEnd > 0) times.pageLoad = navigation.loadEventEnd;
+	return times;
+}
+//#endregion
+export { webVitals };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/web-vitals.const.ts","../src/web-vitals.ts"],"sourcesContent":["export const PERFORMANCE_EVENT_TYPE = 'Performance'\nexport const WEB_CONTEXT = 'web'\nexport const WEB_VITALS_PLUGIN_NAME = 'web-vitals'\n","import type { Client, StatsPlugin } from '@codeserk/forge-stats'\nimport { type Metric, onCLS, onFCP, onINP, onLCP, onTTFB } from 'web-vitals'\n\nimport { PERFORMANCE_EVENT_TYPE, WEB_CONTEXT, WEB_VITALS_PLUGIN_NAME } from './web-vitals.const'\nimport type { WebVitalsOptions } from './web-vitals.types'\n\n/**\n * Returns the plugin that tracks the web vitals of the page load as one `Performance` event.\n * @param options\n * @returns the plugin for `init`\n */\nexport function webVitals(options: WebVitalsOptions): StatsPlugin {\n  return {\n    name: WEB_VITALS_PLUGIN_NAME,\n    setup: (client) => captureWebVitals(client, options),\n  }\n}\n\n/**\n * Tracks the web vitals through the client the first time the page is hidden, when INP and CLS are final.\n * @param client\n * @param options\n */\nfunction captureWebVitals(client: Client, { getRoute }: WebVitalsOptions): void {\n  const metrics: Record<string, number> = {}\n  const collect = (metric: Metric) => {\n    metrics[metric.name.toLowerCase()] = metric.value\n  }\n  onLCP(collect)\n  onINP(collect)\n  onCLS(collect)\n  onFCP(collect)\n  onTTFB(collect)\n\n  const onVisibilityChange = () => {\n    if (document.visibilityState !== 'hidden') {\n      return\n    }\n\n    document.removeEventListener('visibilitychange', onVisibilityChange)\n    client.track({\n      type: PERFORMANCE_EVENT_TYPE,\n      name: getRoute(),\n      data: { context: WEB_CONTEXT, ...metrics, ...loadTimes() },\n    })\n  }\n  document.addEventListener('visibilitychange', onVisibilityChange)\n}\n\n/**\n * Returns the DOMContentLoaded and load times reached so far.\n * @returns the times in ms, as `domLoad` and `pageLoad`\n */\nfunction loadTimes(): Record<string, number> {\n  const [navigation] = performance.getEntriesByType('navigation') as PerformanceNavigationTiming[]\n  const times: Record<string, number> = {}\n  if (navigation?.domContentLoadedEventEnd > 0) {\n    times.domLoad = navigation.domContentLoadedEventEnd\n  }\n  if (navigation?.loadEventEnd > 0) {\n    times.pageLoad = navigation.loadEventEnd\n  }\n\n  return times\n}\n"],"mappings":";;;AAAA,MAAa,yBAAyB;AAEtC,MAAa,yBAAyB;;;;;;;;ACStC,SAAgB,UAAU,SAAwC;AAChE,QAAO;EACL,MAAM;EACN,QAAQ,WAAW,iBAAiB,QAAQ,QAAQ;EACrD;;;;;;;AAQH,SAAS,iBAAiB,QAAgB,EAAE,YAAoC;CAC9E,MAAM,UAAkC,EAAE;CAC1C,MAAM,WAAW,WAAmB;AAClC,UAAQ,OAAO,KAAK,aAAa,IAAI,OAAO;;AAE9C,OAAM,QAAQ;AACd,OAAM,QAAQ;AACd,OAAM,QAAQ;AACd,OAAM,QAAQ;AACd,QAAO,QAAQ;CAEf,MAAM,2BAA2B;AAC/B,MAAI,SAAS,oBAAoB,SAC/B;AAGF,WAAS,oBAAoB,oBAAoB,mBAAmB;AACpE,SAAO,MAAM;GACX,MAAM;GACN,MAAM,UAAU;GAChB,MAAM;IAAE,SAAA;IAAsB,GAAG;IAAS,GAAG,WAAW;IAAE;GAC3D,CAAC;;AAEJ,UAAS,iBAAiB,oBAAoB,mBAAmB;;;;;;AAOnE,SAAS,YAAoC;CAC3C,MAAM,CAAC,cAAc,YAAY,iBAAiB,aAAa;CAC/D,MAAM,QAAgC,EAAE;AACxC,KAAI,YAAY,2BAA2B,EACzC,OAAM,UAAU,WAAW;AAE7B,KAAI,YAAY,eAAe,EAC7B,OAAM,WAAW,WAAW;AAG9B,QAAO"}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@codeserk/forge-stats-web-vitals",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Web vitals plugin for Forge Stats. Tracks the web performance of every page load as one Performance event.",
+  "license": "MIT",
+  "keywords": [
+    "forge",
+    "analytics",
+    "stats",
+    "performance",
+    "web-vitals"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "jest",
+    "lint": "eslint src",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major",
+    "publish:dry": "npm publish --dry-run",
+    "publish:npm": "npm run build && npm publish"
+  },
+  "peerDependencies": {
+    "@codeserk/forge-stats": "^0.4.0"
+  },
+  "dependencies": {
+    "web-vitals": "^6.2.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.6",
+    "tsdown": "^0.21.4",
+    "typescript": "^5.7.0"
+  }
+}