fix: update Web Vitals handling and improve documentation

Author: Dobrunia

packages/javascript/README.md

@@ -12,7 +12,7 @@ Error tracking for JavaScript/TypeScript applications.
 - 🌟 Source maps consuming
 - 💬 Console logs tracking
 - 🧊 Main-thread blocking detection (Long Tasks + LoAF, Chromium-only)
-- 📊 Aggregated Web Vitals issues monitoring
+- 📊 Web Vitals issues monitoring
 - ⚙️ Unified `issues` configuration (errors + performance detectors)
 - <img src="https://cdn.svglogos.dev/logos/vue.svg" width="16" height="16"> &nbsp;Vue support
 - <img src="https://cdn.svglogos.dev/logos/react.svg" width="16" height="16">  &nbsp;React support
@@ -255,16 +255,15 @@ Freeze detectors use two complementary APIs:
 - **Long Tasks API** — browser reports tasks taking longer than 50 ms.
 - **Long Animation Frames (LoAF)** — browser reports frames taking longer than 50 ms with richer script attribution (Chrome 123+, Edge 123+).
 
-Both freeze detectors are disabled by default. If enabled and one API is unsupported, the other still works.
+Both freeze detectors are enabled by default. If one API is unsupported, the other still works.
 Each detected freeze is reported immediately with detailed context (duration, blocking time, scripts involved, etc.).
 `thresholdMs` is an additional Hawk filter on top of browser reporting. Hawk emits an issue when measured duration is equal to or greater than this value. Values below `50ms` are clamped to `50ms`.
 
-### Web Vitals (Aggregated)
+### Web Vitals
 
-When `issues.webVitals` is enabled, Hawk collects Core Web Vitals (`LCP`, `FCP`, `TTFB`, `INP`, `CLS`) and sends a single issue event when at least one metric is rated `poor`.
-Reporting happens when all five metrics are collected, or earlier on timeout/page unload to avoid waiting indefinitely on pages where some metrics never fire.
+When `issues.webVitals` is enabled, Hawk listens to Core Web Vitals (`LCP`, `FCP`, `TTFB`, `INP`, `CLS`) and sends a dedicated issue event for each metric that is rated `poor`.
 
-The event context contains all metrics with:
+Each Web Vitals issue context contains metric fields:
 - `value`
 - `rating`
 - `delta`
@@ -311,9 +310,9 @@ const hawk = new HawkCatcher({
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `errors` | `boolean` | `true` | Enable global errors handling (`window.onerror` and `unhandledrejection`). |
-| `webVitals` | `boolean` | `false` | Collect all Core Web Vitals and send one issue event when at least one metric is rated `poor`. Requires optional `web-vitals` dependency. |
-| `longTasks` | `boolean` or `{ thresholdMs?: number }` | `false` | `false` disables. `true` enables with default threshold. Object enables and uses `thresholdMs` when valid; otherwise fallback threshold `70ms` is used (minimum effective value `50ms`). |
-| `longAnimationFrames` | `boolean` or `{ thresholdMs?: number }` | `false` | `false` disables. `true` enables with default threshold. Object enables and uses `thresholdMs` when valid; otherwise fallback threshold `200ms` is used (minimum effective value `50ms`). Requires Chrome 123+ / Edge 123+. |
+| `webVitals` | `boolean` | `true` | Listen to Core Web Vitals and send one issue event per metric when that metric is rated `poor`. Requires optional `web-vitals` dependency. |
+| `longTasks` | `boolean` or `{ thresholdMs?: number }` | `true` | `false` disables. `true` enables with default threshold. Object enables and uses `thresholdMs` when valid; otherwise fallback threshold `70ms` is used (minimum effective value `50ms`). |
+| `longAnimationFrames` | `boolean` or `{ thresholdMs?: number }` | `true` | `false` disables. `true` enables with default threshold. Object enables and uses `thresholdMs` when valid; otherwise fallback threshold `200ms` is used (minimum effective value `50ms`). Requires Chrome 123+ / Edge 123+. |
 
 ## Source maps consuming
 

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

@@ -6,8 +6,7 @@ import type {
   LoAFScript,
   LongTaskPerformanceEntry,
   WebVitalMetric,
-  WebVitalRating,
-  WebVitalsReport
+  WebVitalRating
 } from '../types/issues';
 import { compactJson } from '../utils/compactJson';
 import log from '../utils/log';
@@ -27,11 +26,6 @@ export const DEFAULT_LOAF_THRESHOLD_MS = 200;
  * Prevents overly aggressive configuration and event spam.
  */
 export const MIN_ISSUE_THRESHOLD_MS = 50;
-/**
- * Maximum waiting time for Web Vitals aggregation before forced report attempt.
- */
-export const WEB_VITALS_REPORT_TIMEOUT_MS = 10000;
-
 /**
  * Web Vitals "good/poor" boundaries used to enrich issue summaries.
  */
@@ -43,12 +37,6 @@ const METRIC_THRESHOLDS: Record<string, [good: number, poor: number]> = {
   CLS: [0.1, 0.25],
 };
 
-/**
- * Number of Core Web Vitals currently collected by this monitor.
- * We wait for all metrics first, then fallback to timeout/pagehide flush.
- */
-const TOTAL_WEB_VITALS = 5;
-
 /**
  * Minimal Web Vitals API contract used by this monitor.
  * Supports module import and global CDN exposure (`window.webVitals`).
@@ -72,8 +60,6 @@ export class PerformanceIssuesMonitor {
   private longTaskObserver: PerformanceObserver | null = null;
   /** Active observer for Long Animation Frames API. */
   private loafObserver: PerformanceObserver | null = null;
-  /** Cleanup hook for Web Vitals timeout/pagehide listeners. */
-  private webVitalsCleanup: (() => void) | null = null;
   /** Prevents duplicate initialization and duplicate issue streams. */
   private isInitialized = false;
   /** Marks monitor as stopped to ignore async callbacks after destroy. */
@@ -93,21 +79,21 @@ export class PerformanceIssuesMonitor {
     this.isInitialized = true;
     this.destroyed = false;
 
-    if (options.longTasks !== undefined && options.longTasks !== false) {
+    if (options.longTasks !== false) {
       this.observeLongTasks(
         resolveThreshold(resolveThresholdOption(options.longTasks), DEFAULT_LONG_TASK_THRESHOLD_MS),
         onIssue
       );
     }
 
-    if (options.longAnimationFrames !== undefined && options.longAnimationFrames !== false) {
+    if (options.longAnimationFrames !== false) {
       this.observeLoAF(
         resolveThreshold(resolveThresholdOption(options.longAnimationFrames), DEFAULT_LOAF_THRESHOLD_MS),
         onIssue
       );
     }
 
-    if (options.webVitals === true) {
+    if (options.webVitals !== false) {
       this.observeWebVitals(onIssue);
     }
   }
@@ -123,10 +109,8 @@ export class PerformanceIssuesMonitor {
     this.isInitialized = false;
     this.longTaskObserver?.disconnect();
     this.loafObserver?.disconnect();
-    this.webVitalsCleanup?.();
     this.longTaskObserver = null;
     this.loafObserver = null;
-    this.webVitalsCleanup = null;
   }
 
   /**
@@ -255,8 +239,7 @@ export class PerformanceIssuesMonitor {
   }
 
   /**
-   * Observe Web Vitals and emit a single aggregated poor report.
-   * Reports when all metrics are collected or on timeout/pagehide fallback.
+   * Observe Web Vitals and emit one issue per poor metric.
    *
    * Resolution strategy:
    * 1) Use global `window.webVitals` when available (CDN scenario)
@@ -271,125 +254,46 @@ export class PerformanceIssuesMonitor {
         return;
       }
 
-      const collected: Record<string, WebVitalMetric> = {};
-      let reported = false;
-      let timeoutId: ReturnType<typeof setTimeout> | null = null;
-      let handlePageHide: (() => void) | null = null;
-
-      /**
-       * Clears timeout and page lifecycle listener bound for this monitor run.
-       */
-      const cleanup = (): void => {
-        if (timeoutId !== null) {
-          clearTimeout(timeoutId);
-          timeoutId = null;
-        }
-
-        if (typeof window !== 'undefined' && handlePageHide !== null) {
-          window.removeEventListener('pagehide', handlePageHide);
-        }
-      };
+      const reportedPoorMetrics = new Set<string>();
 
       /**
-       * 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
+       * Emits one issue event for a poor metric.
+       * Same metric name is reported only once.
        */
-      const tryReport = (force: boolean): void => {
-        if (this.destroyed || reported) {
-          return;
-        }
-
-        const metrics = Object.values(collected);
-
-        if (metrics.length === 0) {
+      const reportPoorMetric = (metric: { name: string; value: number; rating: WebVitalRating; delta: number }): void => {
+        if (this.destroyed || metric.rating !== 'poor') {
           return;
         }
 
-        if (!force && metrics.length < TOTAL_WEB_VITALS) {
+        if (reportedPoorMetrics.has(metric.name)) {
           return;
         }
 
-        const poor = metrics.filter((metric) => metric.rating === 'poor');
-
-        if (poor.length === 0) {
-          return;
-        }
+        reportedPoorMetrics.add(metric.name);
 
-        reported = true;
-        cleanup();
-
-        const summary = poor
-          .map((metric) => {
-            const thresholds = METRIC_THRESHOLDS[metric.name];
-            const threshold = thresholds ? ` (poor > ${formatValue(metric.name, thresholds[1])})` : '';
-
-            return `${metric.name} = ${formatValue(metric.name, metric.value)}${threshold}`;
-          })
-          .join(', ');
-
-        const report: WebVitalsReport = {
-          summary,
-          poorCount: poor.length,
-          metrics: { ...collected },
-        };
+        const thresholds = METRIC_THRESHOLDS[metric.name];
+        const thresholdNote = thresholds ? ` (poor > ${formatValue(metric.name, thresholds[1])})` : '';
+        const summary = `${metric.name} = ${formatValue(metric.name, metric.value)}${thresholdNote}`;
 
         onIssue({
-          title: `Poor Web Vitals: ${summary}`,
+          title: `Poor Web Vital: ${summary}`,
           context: {
-            webVitals: serializeWebVitalsReport(report),
+            webVitals: serializeWebVitalMetric(metric),
           },
         });
       };
 
-      /**
-       * 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) {
-          return;
-        }
-
-        collected[metric.name] = {
-          name: metric.name,
-          value: metric.value,
-          rating: metric.rating,
-          delta: metric.delta,
-        };
-
-        tryReport(false);
-      };
-
-      handlePageHide = (): void => {
-        tryReport(true);
-      };
-
-      timeoutId = setTimeout(() => {
-        tryReport(true);
-      }, WEB_VITALS_REPORT_TIMEOUT_MS);
-
-      if (typeof window !== 'undefined' && handlePageHide !== null) {
-        window.addEventListener('pagehide', handlePageHide);
-      }
-
-      this.webVitalsCleanup = cleanup;
-
-      onCLS(collect);
-      onINP(collect);
-      onLCP(collect);
-      onFCP(collect);
-      onTTFB(collect);
-    })
-      .catch(() => {
-        log(
-          'Web Vitals tracking requires `web-vitals` (npm) or global `window.webVitals` (CDN).',
-          'warn'
-        );
-      });
+      onCLS(reportPoorMetric);
+      onINP(reportPoorMetric);
+      onLCP(reportPoorMetric);
+      onFCP(reportPoorMetric);
+      onTTFB(reportPoorMetric);
+    }).catch(() => {
+      log(
+        'Web Vitals tracking requires `web-vitals` (npm) or global `window.webVitals` (CDN).',
+        'warn'
+      );
+    });
   }
 }
 
@@ -507,25 +411,15 @@ function serializeScript(script: LoAFScript): Json {
 }
 
 /**
- * Serializes aggregated Web Vitals report into event context payload.
+ * Serializes single Web Vital metric into event context payload.
  *
- * @param report aggregated vitals report
+ * @param metric web vital metric
  */
-function serializeWebVitalsReport(report: WebVitalsReport): Json {
-  const metrics = Object.entries(report.metrics).reduce<Json>((acc, [name, metric]) => {
-    acc[name] = compactJson([
-      ['name', metric.name],
-      ['value', metric.value],
-      ['rating', metric.rating],
-      ['delta', metric.delta],
-    ]);
-
-    return acc;
-  }, {});
-
+function serializeWebVitalMetric(metric: WebVitalMetric): Json {
   return compactJson([
-    ['summary', report.summary],
-    ['poorCount', report.poorCount],
-    ['metrics', metrics],
+    ['name', metric.name],
+    ['value', metric.value],
+    ['rating', metric.rating],
+    ['delta', metric.delta],
   ]);
 }

packages/javascript/src/catcher.ts

@@ -326,8 +326,8 @@ export default class Catcher {
   private configureIssues(settings: HawkInitialSettings): void {
     const issues = settings.issues ?? {};
     const shouldHandleGlobalErrors = settings.disableGlobalErrorsHandling !== true && issues.errors !== false;
-    const shouldDetectPerformanceIssues = (issues.longTasks !== undefined && issues.longTasks !== false)
-      || (issues.longAnimationFrames !== undefined && issues.longAnimationFrames !== false)
+    const shouldDetectPerformanceIssues = issues.longTasks !== false
+      || issues.longAnimationFrames !== false
       || issues.webVitals === true;
 
     if (shouldHandleGlobalErrors) {

packages/javascript/src/types/issues.ts

@@ -18,7 +18,7 @@ export interface PerformanceIssuesOptions {
   /**
    * Enable aggregated Web Vitals monitoring.
    *
-   * @default false
+   * @default true
    */
   webVitals?: boolean;
 
@@ -28,7 +28,7 @@ export interface PerformanceIssuesOptions {
    * Any other value enables it with default threshold.
    * If `thresholdMs` is a valid number greater than or equal to 50, it is used.
    *
-   * @default false
+   * @default true
    */
   longTasks?: boolean | PerformanceIssueThresholdOptions;
 
@@ -38,7 +38,7 @@ export interface PerformanceIssuesOptions {
    * Any other value enables it with default threshold.
    * If `thresholdMs` is a valid number greater than or equal to 50, it is used.
    *
-   * @default false
+   * @default true
    */
   longAnimationFrames?: boolean | PerformanceIssueThresholdOptions;
 }