chore: cdn support

Author: Dobrunia

packages/javascript/README.md

@@ -269,7 +269,9 @@ The event context contains all metrics with:
 - `rating`
 - `delta`
 
-`web-vitals` is an optional peer dependency and is loaded only when `issues.webVitals: true`.
+`web-vitals` is optional and used only when `issues.webVitals: true`:
+- NPM/ESM setup: install `web-vitals` as dependency.
+- CDN setup: expose global `window.webVitals` before Hawk initialization.
 
 ### Disabling
 

packages/javascript/src/addons/performance-issues.ts

@@ -49,6 +49,18 @@ const METRIC_THRESHOLDS: Record<string, [good: number, poor: number]> = {
  */
 const TOTAL_WEB_VITALS = 5;
 
+/**
+ * Minimal Web Vitals API contract used by this monitor.
+ * Supports module import and global CDN exposure (`window.webVitals`).
+ */
+type WebVitalsApi = {
+  onCLS: (callback: (metric: { name: string; value: number; rating: WebVitalRating; delta: number }) => void) => void;
+  onINP: (callback: (metric: { name: string; value: number; rating: WebVitalRating; delta: number }) => void) => void;
+  onLCP: (callback: (metric: { name: string; value: number; rating: WebVitalRating; delta: number }) => void) => void;
+  onFCP: (callback: (metric: { name: string; value: number; rating: WebVitalRating; delta: number }) => void) => void;
+  onTTFB: (callback: (metric: { name: string; value: number; rating: WebVitalRating; delta: number }) => void) => void;
+};
+
 /**
  * Performance issues monitor handles:
  * - Long Tasks
@@ -246,10 +258,15 @@ export class PerformanceIssuesMonitor {
    * Observe Web Vitals and emit a single aggregated poor report.
    * Reports when all metrics are collected or on timeout/pagehide fallback.
    *
+   * Resolution strategy:
+   * 1) Use global `window.webVitals` when available (CDN scenario)
+   * 2) Fallback to dynamic import of `web-vitals` (NPM/ESM scenario)
+   * 3) Log warning if neither is available
+   *
    * @param onIssue issue callback
    */
   private observeWebVitals(onIssue: (event: PerformanceIssueEvent) => void): void {
-    void import('web-vitals').then(({ onCLS, onINP, onLCP, onFCP, onTTFB }) => {
+    void resolveWebVitalsApi().then(({ onCLS, onINP, onLCP, onFCP, onTTFB }) => {
       if (this.destroyed) {
         return;
       }
@@ -277,6 +294,8 @@ export class PerformanceIssuesMonitor {
        * Tries to emit an aggregated Web Vitals issue.
        * When `force` is false, waits for all vitals.
        * When `force` is true, emits with currently collected metrics.
+       *
+       * @param force
        */
       const tryReport = (force: boolean): void => {
         if (this.destroyed || reported) {
@@ -327,6 +346,8 @@ export class PerformanceIssuesMonitor {
 
       /**
        * Collects latest metric snapshot per metric name.
+       *
+       * @param metric
        */
       const collect = (metric: { name: string; value: number; rating: WebVitalRating; delta: number }): void => {
         if (this.destroyed || reported) {
@@ -362,19 +383,19 @@ export class PerformanceIssuesMonitor {
       onLCP(collect);
       onFCP(collect);
       onTTFB(collect);
-    }).catch(() => {
-      log(
-        'web-vitals package is required for Web Vitals tracking. Install it with: npm i web-vitals',
-        'warn'
-      );
-    });
+    })
+      .catch(() => {
+        log(
+          'Web Vitals tracking requires `web-vitals` (npm) or global `window.webVitals` (CDN).',
+          'warn'
+        );
+      });
   }
 }
 
 /**
  * Checks if browser supports a performance entry type.
  *
- *
  * @param type performance entry type
  */
 function supportsEntryType(type: string): boolean {
@@ -392,7 +413,6 @@ function supportsEntryType(type: string): boolean {
 /**
  * Resolves threshold from user input and applies global minimum clamp.
  *
- *
  * @param value custom threshold
  * @param fallback default threshold
  */
@@ -408,7 +428,6 @@ function resolveThreshold(value: number | undefined, fallback: number): number {
  * Returns custom threshold from detector config object.
  * Boolean options use default threshold.
  *
- *
  * @param value detector config value
  */
 function resolveThresholdOption(value: boolean | { thresholdMs?: number }): number | undefined {
@@ -419,10 +438,47 @@ function resolveThresholdOption(value: boolean | { thresholdMs?: number }): numb
   return undefined;
 }
 
+/**
+ * Resolves Web Vitals API from global scope or dynamic module import.
+ */
+async function resolveWebVitalsApi(): Promise<WebVitalsApi> {
+  const globalApi = getGlobalWebVitalsApi();
+
+  if (globalApi) {
+    return globalApi;
+  }
+
+  const moduleApi = await import('web-vitals');
+
+  return moduleApi as unknown as WebVitalsApi;
+}
+
+/**
+ * Returns global Web Vitals API when Hawk is used via CDN.
+ */
+function getGlobalWebVitalsApi(): WebVitalsApi | null {
+  if (typeof globalThis === 'undefined') {
+    return null;
+  }
+
+  const candidate = (globalThis as { webVitals?: unknown }).webVitals;
+
+  if (!candidate || typeof candidate !== 'object') {
+    return null;
+  }
+
+  const api = candidate as Partial<WebVitalsApi>;
+
+  if (!api.onCLS || !api.onINP || !api.onLCP || !api.onFCP || !api.onTTFB) {
+    return null;
+  }
+
+  return api as WebVitalsApi;
+}
+
 /**
  * Formats Web Vitals metric value for readable summary.
  *
- *
  * @param name metric name
  * @param value metric value
  */
@@ -433,7 +489,6 @@ function formatValue(name: string, value: number): string {
 /**
  * Serializes LoAF script timing into compact JSON payload.
  *
- *
  * @param script loaf script entry
  */
 function serializeScript(script: LoAFScript): Json {
@@ -454,7 +509,6 @@ function serializeScript(script: LoAFScript): Json {
 /**
  * Serializes aggregated Web Vitals report into event context payload.
  *
- *
  * @param report aggregated vitals report
  */
 function serializeWebVitalsReport(report: WebVitalsReport): Json {

packages/javascript/tests/performance-issues.test.ts

@@ -74,12 +74,37 @@ function mockWebVitals() {
   };
 }
 
+function mockGlobalWebVitals() {
+  const callbacks: Record<string, ReportCallback | undefined> = {};
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (globalThis as any).webVitals = {
+    onCLS: (cb: ReportCallback) => { callbacks.CLS = cb; },
+    onINP: (cb: ReportCallback) => { callbacks.INP = cb; },
+    onLCP: (cb: ReportCallback) => { callbacks.LCP = cb; },
+    onFCP: (cb: ReportCallback) => { callbacks.FCP = cb; },
+    onTTFB: (cb: ReportCallback) => { callbacks.TTFB = cb; },
+  };
+
+  return {
+    emit(metric: Metric): void {
+      callbacks[metric.name]?.(metric);
+    },
+    cleanup(): void {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      delete (globalThis as any).webVitals;
+    },
+  };
+}
+
 describe('PerformanceIssuesMonitor', () => {
   beforeEach(() => {
     vi.resetModules();
     vi.unstubAllGlobals();
     vi.restoreAllMocks();
     vi.useRealTimers();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    delete (globalThis as any).webVitals;
     MockPerformanceObserver.reset();
     vi.stubGlobal('PerformanceObserver', MockPerformanceObserver as unknown as typeof PerformanceObserver);
   });
@@ -88,6 +113,8 @@ describe('PerformanceIssuesMonitor', () => {
     vi.unstubAllGlobals();
     vi.restoreAllMocks();
     vi.useRealTimers();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    delete (globalThis as any).webVitals;
   });
 
   it('should clamp long task threshold to 50ms minimum', async () => {
@@ -208,4 +235,22 @@ describe('PerformanceIssuesMonitor', () => {
     expect(onIssue.mock.calls[0][0].title).toContain('Poor Web Vitals');
     expect(onIssue.mock.calls[0][0].context).toHaveProperty('webVitals');
   });
+
+  it('should use global webVitals API when available (CDN scenario)', async () => {
+    vi.useFakeTimers();
+    const globalWebVitals = mockGlobalWebVitals();
+    const { PerformanceIssuesMonitor } = await import('../src/addons/performance-issues');
+    const onIssue = vi.fn();
+    const monitor = new PerformanceIssuesMonitor();
+
+    monitor.init({ longTasks: false, longAnimationFrames: false, webVitals: true }, onIssue);
+    await vi.dynamicImportSettled();
+
+    globalWebVitals.emit({ name: 'INP', value: 600, rating: 'poor', delta: 600 });
+    vi.advanceTimersByTime(WEB_VITALS_REPORT_TIMEOUT_MS);
+
+    expect(onIssue).toHaveBeenCalledTimes(1);
+    expect(onIssue.mock.calls[0][0].title).toContain('Poor Web Vitals');
+    globalWebVitals.cleanup();
+  });
 });