Web Vitals

Automatically capture Core Web Vitals (LCP, CLS, INP, TTFB, FCP) and route-level performance metrics with zero configuration.

Quick Setup

Add the metrics component to your root layout:

typescript

1// app/layout.tsx
2import { VestigMetrics } from '@vestig/next/metrics'
3 
4export default function RootLayout({ children }: { children: React.ReactNode }) {
5  return (
6    <html>
7      <body>
8        {children}
9        <VestigMetrics />
10      </body>
11    </html>
12  )
13}

Metrics are automatically captured and displayed in the Dev Overlay's Metrics tab.

Configuration

Prop	Type	Default	Description
`enabled`	`boolean`	`true`	Enable/disable metric collection
`sampleRate`	`number`	`1.0` (dev) / `0.1` (prod)	Percentage of sessions to track (0.0 - 1.0)
`reportEndpoint`	`string`	`'/api/vestig/metrics'`	Endpoint for sending metrics
`reportPoorImmediately`	`boolean`	`true`	Send "poor" ratings immediately (don't wait for batch)
`captureRouteMetrics`	`boolean`	`true`	Track route navigation timing
`debug`	`boolean`	`false`	Log metrics to console

Captured Metrics

Core Web Vitals

Metric	Description	Good	Poor
LCP	Largest Contentful Paint - Loading performance	< 2.5s	> 4.0s
CLS	Cumulative Layout Shift - Visual stability	< 0.1	> 0.25
INP	Interaction to Next Paint - Interactivity	< 200ms	> 500ms
TTFB	Time to First Byte - Server responsiveness	< 800ms	> 1.8s
FCP	First Contentful Paint - Perceived load speed	< 1.8s	> 3.0s

Route Metrics

Render Time: Time to render the page
Hydration Time: Time for React hydration
Data Fetch Time: Time spent fetching data

Using Hooks

Access metrics data in your components:

typescript

1import {
2  useWebVitalsData,
3  useWebVitalsSummary,
4  useRouteMetricsData,
5} from '@vestig/next/metrics'
6 
7function MetricsDashboard() {
8  // Get latest Web Vitals values
9  const vitals = useWebVitalsData()
10  // { LCP: { value, rating }, CLS: {...}, ... }
11 
12  // Get summary statistics (avg, p75, count)
13  const summary = useWebVitalsSummary()
14  // { LCP: { avg, p75, rating, count }, ... }
15 
16  // Get route metrics
17  const route = useRouteMetricsData()
18  // { pathname, renderTime, hydrationTime, dataFetchTime }
19 
20  return (
21    <div>
22      <h2>LCP: {vitals.LCP?.value}ms</h2>
23      <p>Rating: {vitals.LCP?.rating}</p>
24      <p>P75: {summary.LCP?.p75}ms</p>
25    </div>
26  )
27}

Rating System

Each metric receives a rating based on Google's Core Web Vitals thresholds:

🟢 Good - Meets the recommended threshold
🟡 Needs Improvement - Between good and poor
🔴 Poor - Exceeds the poor threshold

Production Setup

For production, use sampling to reduce data volume:

typescript

1<VestigMetrics
2  sampleRate={0.1}  // Track 10% of sessions
3  reportPoorImmediately={true}  // Always report poor experiences
4  reportEndpoint="/api/metrics"
5/>

Metrics API Endpoint

Create an endpoint to receive metrics:

typescript

1// app/api/metrics/route.ts
2import { NextRequest, NextResponse } from 'next/server'
3 
4export async function POST(request: NextRequest) {
5  const metrics = await request.json()
6 
7  // Send to your analytics service
8  await sendToAnalytics(metrics)
9 
10  return NextResponse.json({ success: true })
11}

Best Practices

1. Use Sampling in Production

Full metric collection on every user adds overhead. Sample a percentage:

typescript

1<VestigMetrics sampleRate={0.1} />  // 10% sampling

2. Report Poor Metrics Immediately

Don't wait to batch poor experiences:

typescript

1<VestigMetrics reportPoorImmediately={true} />

3. Combine with Dev Overlay

Use the Dev Overlay's Metrics tab during development:

typescript

1{process.env.NODE_ENV === 'development' && <VestigDevOverlay />}
2<VestigMetrics />

Threshold Reference

typescript

1import { THRESHOLDS, getRating } from '@vestig/next/metrics'
2 
3// Check thresholds
4console.log(THRESHOLDS.LCP)
5// { good: 2500, poor: 4000, unit: 'ms' }
6 
7// Get rating for a value
8const rating = getRating('LCP', 3000)
9// 'needs-improvement'

Next Steps

Dev Overlay — View metrics in real-time
Error Boundary — Handle errors gracefully
Logging Basics — Understand structured logging

Web Vitals

Automatically capture Core Web Vitals (LCP, CLS, INP, TTFB, FCP) and route-level performance metrics with zero configuration.

Quick Setup

Add the metrics component to your root layout:

typescript

1// app/layout.tsx
2import { VestigMetrics } from '@vestig/next/metrics'
3 
4export default function RootLayout({ children }: { children: React.ReactNode }) {
5  return (
6    <html>
7      <body>
8        {children}
9        <VestigMetrics />
10      </body>
11    </html>
12  )
13}

Metrics are automatically captured and displayed in the Dev Overlay's Metrics tab.

Configuration

Prop	Type	Default	Description
`enabled`	`boolean`	`true`	Enable/disable metric collection
`sampleRate`	`number`	`1.0` (dev) / `0.1` (prod)	Percentage of sessions to track (0.0 - 1.0)
`reportEndpoint`	`string`	`'/api/vestig/metrics'`	Endpoint for sending metrics
`reportPoorImmediately`	`boolean`	`true`	Send "poor" ratings immediately (don't wait for batch)
`captureRouteMetrics`	`boolean`	`true`	Track route navigation timing
`debug`	`boolean`	`false`	Log metrics to console

Captured Metrics

Core Web Vitals

Metric	Description	Good	Poor
LCP	Largest Contentful Paint - Loading performance	< 2.5s	> 4.0s
CLS	Cumulative Layout Shift - Visual stability	< 0.1	> 0.25
INP	Interaction to Next Paint - Interactivity	< 200ms	> 500ms
TTFB	Time to First Byte - Server responsiveness	< 800ms	> 1.8s
FCP	First Contentful Paint - Perceived load speed	< 1.8s	> 3.0s

Route Metrics

Render Time: Time to render the page
Hydration Time: Time for React hydration
Data Fetch Time: Time spent fetching data

Using Hooks

Access metrics data in your components:

typescript

1import {
2  useWebVitalsData,
3  useWebVitalsSummary,
4  useRouteMetricsData,
5} from '@vestig/next/metrics'
6 
7function MetricsDashboard() {
8  // Get latest Web Vitals values
9  const vitals = useWebVitalsData()
10  // { LCP: { value, rating }, CLS: {...}, ... }
11 
12  // Get summary statistics (avg, p75, count)
13  const summary = useWebVitalsSummary()
14  // { LCP: { avg, p75, rating, count }, ... }
15 
16  // Get route metrics
17  const route = useRouteMetricsData()
18  // { pathname, renderTime, hydrationTime, dataFetchTime }
19 
20  return (
21    <div>
22      <h2>LCP: {vitals.LCP?.value}ms</h2>
23      <p>Rating: {vitals.LCP?.rating}</p>
24      <p>P75: {summary.LCP?.p75}ms</p>
25    </div>
26  )
27}

Rating System

Each metric receives a rating based on Google's Core Web Vitals thresholds:

🟢 Good - Meets the recommended threshold
🟡 Needs Improvement - Between good and poor
🔴 Poor - Exceeds the poor threshold

Production Setup

For production, use sampling to reduce data volume:

typescript

1<VestigMetrics
2  sampleRate={0.1}  // Track 10% of sessions
3  reportPoorImmediately={true}  // Always report poor experiences
4  reportEndpoint="/api/metrics"
5/>

Metrics API Endpoint

Create an endpoint to receive metrics:

typescript

1// app/api/metrics/route.ts
2import { NextRequest, NextResponse } from 'next/server'
3 
4export async function POST(request: NextRequest) {
5  const metrics = await request.json()
6 
7  // Send to your analytics service
8  await sendToAnalytics(metrics)
9 
10  return NextResponse.json({ success: true })
11}

Best Practices

1. Use Sampling in Production

Full metric collection on every user adds overhead. Sample a percentage:

typescript

1<VestigMetrics sampleRate={0.1} />  // 10% sampling

2. Report Poor Metrics Immediately

Don't wait to batch poor experiences:

typescript

1<VestigMetrics reportPoorImmediately={true} />

3. Combine with Dev Overlay

Use the Dev Overlay's Metrics tab during development:

typescript

1{process.env.NODE_ENV === 'development' && <VestigDevOverlay />}
2<VestigMetrics />

Threshold Reference

typescript

1import { THRESHOLDS, getRating } from '@vestig/next/metrics'
2 
3// Check thresholds
4console.log(THRESHOLDS.LCP)
5// { good: 2500, poor: 4000, unit: 'ms' }
6 
7// Get rating for a value
8const rating = getRating('LCP', 3000)
9// 'needs-improvement'

Next Steps

Dev Overlay — View metrics in real-time
Error Boundary — Handle errors gracefully
Logging Basics — Understand structured logging