@vestig/next 0.6.0 → 0.8.0

package/dist/metrics/thresholds.js

@@ -0,0 +1,148 @@
+/**
+ * Core Web Vitals Thresholds
+ *
+ * Official thresholds from Google's Core Web Vitals program.
+ * These determine whether a metric is rated as "good", "needs-improvement", or "poor".
+ *
+ * @see https://web.dev/articles/vitals
+ * @packageDocumentation
+ */
+/**
+ * Official Core Web Vitals thresholds
+ *
+ * Values represent the upper bounds:
+ * - good: value < threshold.good
+ * - needs-improvement: threshold.good <= value < threshold.poor
+ * - poor: value >= threshold.poor
+ */
+export const THRESHOLDS = {
+    /**
+     * Largest Contentful Paint
+     * Measures loading performance - when the largest content element becomes visible
+     */
+    LCP: {
+        good: 2500,
+        poor: 4000,
+        unit: 'ms',
+        description: 'Largest Contentful Paint - Loading performance',
+    },
+    /**
+     * Cumulative Layout Shift
+     * Measures visual stability - how much the page layout shifts unexpectedly
+     */
+    CLS: {
+        good: 0.1,
+        poor: 0.25,
+        unit: 'score',
+        description: 'Cumulative Layout Shift - Visual stability',
+    },
+    /**
+     * Interaction to Next Paint
+     * Measures interactivity - time from user interaction to visual feedback
+     */
+    INP: {
+        good: 200,
+        poor: 500,
+        unit: 'ms',
+        description: 'Interaction to Next Paint - Interactivity',
+    },
+    /**
+     * Time to First Byte
+     * Measures server responsiveness - time until first byte of response
+     */
+    TTFB: {
+        good: 800,
+        poor: 1800,
+        unit: 'ms',
+        description: 'Time to First Byte - Server responsiveness',
+    },
+    /**
+     * First Contentful Paint
+     * Measures perceived load speed - when first content is rendered
+     */
+    FCP: {
+        good: 1800,
+        poor: 3000,
+        unit: 'ms',
+        description: 'First Contentful Paint - Perceived load speed',
+    },
+};
+/**
+ * Calculate rating for a metric value
+ *
+ * @param name - Web Vital metric name
+ * @param value - Metric value
+ * @returns Rating based on thresholds
+ *
+ * @example
+ * ```ts
+ * getRating('LCP', 2000) // 'good'
+ * getRating('LCP', 3000) // 'needs-improvement'
+ * getRating('LCP', 5000) // 'poor'
+ * ```
+ */
+export function getRating(name, value) {
+    const threshold = THRESHOLDS[name];
+    if (!threshold)
+        return 'needs-improvement';
+    if (value < threshold.good)
+        return 'good';
+    if (value < threshold.poor)
+        return 'needs-improvement';
+    return 'poor';
+}
+/**
+ * Get human-readable description for a metric
+ */
+export function getMetricDescription(name) {
+    return THRESHOLDS[name]?.description ?? name;
+}
+/**
+ * Get unit for a metric
+ */
+export function getMetricUnit(name) {
+    return THRESHOLDS[name]?.unit ?? 'ms';
+}
+/**
+ * Format a metric value for display
+ *
+ * @param name - Metric name
+ * @param value - Metric value
+ * @returns Formatted string
+ *
+ * @example
+ * ```ts
+ * formatMetricValue('LCP', 2500) // '2.50s'
+ * formatMetricValue('CLS', 0.15) // '0.15'
+ * formatMetricValue('INP', 150)  // '150ms'
+ * ```
+ */
+export function formatMetricValue(name, value) {
+    const unit = getMetricUnit(name);
+    if (unit === 'score') {
+        return value.toFixed(3);
+    }
+    // For timing metrics
+    if (value < 1) {
+        return `${(value * 1000).toFixed(0)}μs`;
+    }
+    if (value < 1000) {
+        return `${value.toFixed(0)}ms`;
+    }
+    return `${(value / 1000).toFixed(2)}s`;
+}
+/**
+ * Rating colors for UI display
+ */
+export const RATING_COLORS = {
+    good: { bg: '#dcfce7', text: '#166534', border: '#86efac' },
+    'needs-improvement': { bg: '#fef3c7', text: '#92400e', border: '#fcd34d' },
+    poor: { bg: '#fee2e2', text: '#991b1b', border: '#fca5a5' },
+};
+/**
+ * Get color scheme for a rating
+ */
+export function getRatingColors(rating) {
+    return RATING_COLORS[rating];
+}
+//# sourceMappingURL=thresholds.js.map

package/dist/metrics/thresholds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thresholds.js","sourceRoot":"","sources":["../../src/metrics/thresholds.ts"],"names":[],"mappings":"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"}

package/dist/metrics/types.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Core Web Vitals and Route Metrics Types
+ *
+ * These types define the structure for capturing and reporting
+ * performance metrics in Next.js applications.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Web Vital metric names
+ * - LCP: Largest Contentful Paint (loading performance)
+ * - CLS: Cumulative Layout Shift (visual stability)
+ * - INP: Interaction to Next Paint (interactivity)
+ * - TTFB: Time to First Byte (server responsiveness)
+ * - FCP: First Contentful Paint (perceived load speed)
+ */
+export type WebVitalName = 'LCP' | 'CLS' | 'INP' | 'TTFB' | 'FCP';
+/**
+ * Rating for a metric based on Core Web Vitals thresholds
+ */
+export type MetricRating = 'good' | 'needs-improvement' | 'poor';
+/**
+ * Navigation type from Performance API
+ */
+export type NavigationType = 'navigate' | 'reload' | 'back-forward' | 'back-forward-cache' | 'prerender' | 'restore';
+/**
+ * Web Vital metric captured from the browser
+ */
+export interface WebVitalMetric {
+    /** Metric name (LCP, CLS, INP, TTFB, FCP) */
+    name: WebVitalName;
+    /** Metric value (ms for timing metrics, score for CLS) */
+    value: number;
+    /** Rating based on Core Web Vitals thresholds */
+    rating: MetricRating;
+    /** Change since last measurement */
+    delta: number;
+    /** Unique identifier for this metric instance */
+    id: string;
+    /** How the page was navigated to */
+    navigationType: NavigationType;
+    /** Entries that contributed to this metric */
+    entries: PerformanceEntry[];
+}
+/**
+ * Route-specific performance metric
+ */
+export interface RouteMetric {
+    /** Route pathname (e.g., /dashboard, /users/[id]) */
+    pathname: string;
+    /** Time to render the route in ms */
+    renderTime: number;
+    /** Time to hydrate the route in ms */
+    hydrationTime: number;
+    /** Time to fetch route data (if applicable) */
+    dataFetchTime?: number;
+    /** ISO timestamp when metric was captured */
+    timestamp: string;
+    /** Request ID for correlation with server logs */
+    requestId?: string;
+}
+/**
+ * Stored metric entry for Dev Overlay and reporting
+ */
+export interface MetricEntry {
+    /** Unique identifier */
+    id: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Type of metric */
+    type: 'web-vital' | 'route' | 'custom';
+    /** Metric name */
+    name: string;
+    /** Metric value */
+    value: number;
+    /** Rating (for web vitals) */
+    rating?: MetricRating;
+    /** Additional metadata */
+    metadata: {
+        pathname?: string;
+        requestId?: string;
+        traceId?: string;
+        userAgent?: string;
+        navigationType?: NavigationType;
+        delta?: number;
+    };
+}
+/**
+ * Histogram bucket for metric visualization
+ */
+export interface HistogramBucket {
+    /** Lower bound of bucket (inclusive) */
+    min: number;
+    /** Upper bound of bucket (exclusive) */
+    max: number;
+    /** Count of values in this bucket */
+    count: number;
+    /** Percentage of total */
+    percentage: number;
+}
+/**
+ * Summary statistics for a metric
+ */
+export interface MetricSummary {
+    /** Metric name */
+    name: string;
+    /** Number of samples */
+    count: number;
+    /** Average value */
+    avg: number;
+    /** Minimum value */
+    min: number;
+    /** Maximum value */
+    max: number;
+    /** 50th percentile (median) */
+    p50: number;
+    /** 75th percentile */
+    p75: number;
+    /** 95th percentile */
+    p95: number;
+    /** 99th percentile */
+    p99: number;
+    /** Overall rating based on p75 */
+    rating: MetricRating;
+}
+/**
+ * Configuration for VestigMetrics component
+ */
+export interface VestigMetricsConfig {
+    /**
+     * Sampling rate for metrics collection (0.0 - 1.0)
+     * @default 1.0 in development, 0.1 in production
+     */
+    sampleRate?: number;
+    /**
+     * Endpoint to report metrics to
+     * @default '/api/vestig/metrics'
+     */
+    reportEndpoint?: string;
+    /**
+     * Enable/disable metrics collection
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Batch interval for reporting in milliseconds
+     * @default 5000
+     */
+    batchInterval?: number;
+    /**
+     * Report immediately when a metric has poor rating
+     * @default true
+     */
+    reportPoorImmediately?: boolean;
+    /**
+     * Capture route metrics (render time, hydration)
+     * @default true
+     */
+    captureRouteMetrics?: boolean;
+    /**
+     * Debug mode - logs metrics to console
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Metrics store state
+ */
+export interface MetricsState {
+    /** All captured metrics */
+    metrics: MetricEntry[];
+    /** Maximum number of metrics to keep in memory */
+    maxMetrics: number;
+    /** Latest value for each web vital */
+    latestVitals: Partial<Record<WebVitalName, MetricEntry>>;
+}
+/**
+ * Metrics store interface
+ */
+export interface MetricsStore {
+    /** Subscribe to store changes */
+    subscribe: (listener: () => void) => () => void;
+    /** Get current snapshot of state */
+    getSnapshot: () => MetricsState;
+    /** Add a new metric */
+    addMetric: (entry: Omit<MetricEntry, 'id' | 'timestamp'>) => void;
+    /** Get histogram for a specific metric */
+    getHistogram: (name: string, bucketCount?: number) => HistogramBucket[];
+    /** Get summary statistics for a metric */
+    getSummary: (name: string) => MetricSummary | null;
+    /** Get all summaries for web vitals */
+    getVitalsSummary: () => Partial<Record<WebVitalName, MetricSummary>>;
+    /** Get the latest metric for a given name */
+    getLatest: (name: string) => MetricEntry | null;
+    /** Clear all metrics */
+    clear: () => void;
+}
+/**
+ * Payload for metrics reporting
+ */
+export interface MetricsReportPayload {
+    /** Metrics to report */
+    metrics: MetricEntry[];
+    /** Client metadata */
+    client: {
+        userAgent: string;
+        pathname: string;
+        timestamp: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/metrics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/metrics/types.ts"],"names":[],"mappings":"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"}

package/dist/metrics/types.js

@@ -0,0 +1,10 @@
+/**
+ * Core Web Vitals and Route Metrics Types
+ *
+ * These types define the structure for capturing and reporting
+ * performance metrics in Next.js applications.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/metrics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/metrics/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/metrics/web-vitals.d.ts

@@ -0,0 +1,72 @@
+/**
+ * VestigMetrics Component
+ *
+ * Drop-in component for capturing Core Web Vitals and route metrics.
+ * Add this to your root layout for automatic performance monitoring.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { VestigMetrics } from '@vestig/next/metrics'
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         {children}
+ *         <VestigMetrics
+ *           sampleRate={0.1}  // 10% sampling in production
+ *           reportEndpoint="/api/vestig/metrics"
+ *         />
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { VestigMetricsConfig } from './types';
+/**
+ * Props for VestigMetrics component
+ */
+export interface VestigMetricsProps extends VestigMetricsConfig {
+}
+/**
+ * VestigMetrics - Core Web Vitals and Route Metrics Component
+ *
+ * This component automatically captures:
+ * - **LCP** (Largest Contentful Paint) - Loading performance
+ * - **CLS** (Cumulative Layout Shift) - Visual stability
+ * - **INP** (Interaction to Next Paint) - Interactivity
+ * - **TTFB** (Time to First Byte) - Server responsiveness
+ * - **FCP** (First Contentful Paint) - Perceived load speed
+ * - **Route metrics** - Navigation and hydration times
+ *
+ * @example Basic usage
+ * ```tsx
+ * <VestigMetrics />
+ * ```
+ *
+ * @example With configuration
+ * ```tsx
+ * <VestigMetrics
+ *   sampleRate={0.1}           // 10% of users
+ *   reportEndpoint="/api/metrics"
+ *   reportPoorImmediately      // Alert on poor metrics
+ *   captureRouteMetrics        // Track route changes
+ *   debug={process.env.NODE_ENV === 'development'}
+ * />
+ * ```
+ *
+ * @example Production setup
+ * ```tsx
+ * <VestigMetrics
+ *   enabled={process.env.NODE_ENV === 'production'}
+ *   sampleRate={0.1}
+ *   reportPoorImmediately
+ * />
+ * ```
+ */
+export declare function VestigMetrics({ enabled, sampleRate, reportEndpoint, reportPoorImmediately, captureRouteMetrics, debug, }: VestigMetricsProps): null;
+//# sourceMappingURL=web-vitals.d.ts.map

package/dist/metrics/web-vitals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-vitals.d.ts","sourceRoot":"","sources":["../../src/metrics/web-vitals.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAIlD;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;CAAG;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,aAAa,CAAC,EAC7B,OAAc,EACd,UAAU,EACV,cAAsC,EACtC,qBAA4B,EAC5B,mBAA0B,EAC1B,KAAa,GACb,EAAE,kBAAkB,GAAG,IAAI,CAwB3B"}

package/dist/metrics/web-vitals.js

@@ -0,0 +1,89 @@
+/**
+ * VestigMetrics Component
+ *
+ * Drop-in component for capturing Core Web Vitals and route metrics.
+ * Add this to your root layout for automatic performance monitoring.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { VestigMetrics } from '@vestig/next/metrics'
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         {children}
+ *         <VestigMetrics
+ *           sampleRate={0.1}  // 10% sampling in production
+ *           reportEndpoint="/api/vestig/metrics"
+ *         />
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+'use client';
+import { useWebVitals } from './hooks/use-web-vitals';
+import { useRouteMetrics } from './hooks/use-route-metrics';
+/**
+ * VestigMetrics - Core Web Vitals and Route Metrics Component
+ *
+ * This component automatically captures:
+ * - **LCP** (Largest Contentful Paint) - Loading performance
+ * - **CLS** (Cumulative Layout Shift) - Visual stability
+ * - **INP** (Interaction to Next Paint) - Interactivity
+ * - **TTFB** (Time to First Byte) - Server responsiveness
+ * - **FCP** (First Contentful Paint) - Perceived load speed
+ * - **Route metrics** - Navigation and hydration times
+ *
+ * @example Basic usage
+ * ```tsx
+ * <VestigMetrics />
+ * ```
+ *
+ * @example With configuration
+ * ```tsx
+ * <VestigMetrics
+ *   sampleRate={0.1}           // 10% of users
+ *   reportEndpoint="/api/metrics"
+ *   reportPoorImmediately      // Alert on poor metrics
+ *   captureRouteMetrics        // Track route changes
+ *   debug={process.env.NODE_ENV === 'development'}
+ * />
+ * ```
+ *
+ * @example Production setup
+ * ```tsx
+ * <VestigMetrics
+ *   enabled={process.env.NODE_ENV === 'production'}
+ *   sampleRate={0.1}
+ *   reportPoorImmediately
+ * />
+ * ```
+ */
+export function VestigMetrics({ enabled = true, sampleRate, reportEndpoint = '/api/vestig/metrics', reportPoorImmediately = true, captureRouteMetrics = true, debug = false, }) {
+    // Determine sample rate based on environment if not specified
+    const effectiveSampleRate = sampleRate ??
+        (typeof window !== 'undefined' && process.env.NODE_ENV === 'production' ? 0.1 : 1.0);
+    // Capture Core Web Vitals
+    useWebVitals({
+        enabled,
+        sampleRate: effectiveSampleRate,
+        reportEndpoint,
+        reportPoorImmediately,
+        debug,
+    });
+    // Capture route metrics
+    useRouteMetrics({
+        enabled: enabled && captureRouteMetrics,
+        reportEndpoint,
+        debug,
+    });
+    // This component doesn't render anything
+    return null;
+}
+//# sourceMappingURL=web-vitals.js.map

package/dist/metrics/web-vitals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-vitals.js","sourceRoot":"","sources":["../../src/metrics/web-vitals.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,YAAY,CAAA;AAGZ,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAO3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,aAAa,CAAC,EAC7B,OAAO,GAAG,IAAI,EACd,UAAU,EACV,cAAc,GAAG,qBAAqB,EACtC,qBAAqB,GAAG,IAAI,EAC5B,mBAAmB,GAAG,IAAI,EAC1B,KAAK,GAAG,KAAK,GACO;IACpB,8DAA8D;IAC9D,MAAM,mBAAmB,GACxB,UAAU;QACV,CAAC,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAErF,0BAA0B;IAC1B,YAAY,CAAC;QACZ,OAAO;QACP,UAAU,EAAE,mBAAmB;QAC/B,cAAc;QACd,qBAAqB;QACrB,KAAK;KACL,CAAC,CAAA;IAEF,wBAAwB;IACxB,eAAe,CAAC;QACf,OAAO,EAAE,OAAO,IAAI,mBAAmB;QACvC,cAAc;QACd,KAAK;KACL,CAAC,CAAA;IAEF,yCAAyC;IACzC,OAAO,IAAI,CAAA;AACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vestig/next",
-	"version": "0.6.0",
+	"version": "0.8.0",
 	"description": "First-class Next.js 15+ integration for vestig logging library. Zero boilerplate, automatic request correlation, full type safety.",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -25,11 +25,29 @@
 		"./config": {
 			"types": "./dist/config/index.d.ts",
 			"import": "./dist/config/index.js"
+		},
+		"./dev": {
+			"types": "./dist/dev/index.d.ts",
+			"import": "./dist/dev/index.js"
+		},
+		"./dev/api": {
+			"types": "./dist/dev/api/index.d.ts",
+			"import": "./dist/dev/api/index.js"
+		},
+		"./metrics": {
+			"types": "./dist/metrics/index.d.ts",
+			"import": "./dist/metrics/index.js"
+		},
+		"./error": {
+			"types": "./dist/error/index.d.ts",
+			"import": "./dist/error/index.js"
+		},
+		"./db": {
+			"types": "./dist/db/index.d.ts",
+			"import": "./dist/db/index.js"
 		}
 	},
-	"files": [
-		"dist"
-	],
+	"files": ["dist"],
 	"sideEffects": false,
 	"scripts": {
 		"build": "tsc",
@@ -68,17 +86,21 @@
 	"peerDependencies": {
 		"next": ">=15.0.0",
 		"react": ">=19.0.0",
+		"react-dom": ">=19.0.0",
 		"vestig": ">=0.2.0"
 	},
 	"dependencies": {
-		"vestig": "workspace:*"
+		"vestig": "workspace:*",
+		"web-vitals": "^4.2.4"
 	},
 	"devDependencies": {
 		"typescript": "catalog:",
 		"@types/node": "catalog:",
 		"@types/react": "catalog:",
+		"@types/react-dom": "catalog:",
 		"next": "catalog:",
-		"react": "catalog:"
+		"react": "catalog:",
+		"react-dom": "catalog:"
 	},
 	"engines": {
 		"node": ">=18"