Adding Analytics to Your Next.js Application – Web Vitals, Error Tracking, and External Reporting

Introduction

Next.js includes built-in support for performance analytics. You can use the useReportWebVitals hook to manage metrics manually, or rely on Vercel’s managed service for automatic collection and visualization.

Client Instrumentation

For advanced tracking, create an instrumentation-client.js or .ts file in your project root. This file runs before your frontend code and is ideal for initializing global analytics or error tracking:

// instrumentation-client.js
console.log('Analytics initialized')

window.addEventListener('error', (event) => {
  reportError(event.error)
})

Creating a WebVitals Component

To report Web Vitals, create a separate client component:

// app/_components/web-vitals.js
'use client'
import { useReportWebVitals } from 'next/web-vitals'

export function WebVitals() {
  useReportWebVitals((metric) => {
    console.log(metric)
  })
}

Then import it in your root layout:

// app/layout.js
import { WebVitals } from './_components/web-vitals'

export default function Layout({ children }) {
  return (
    <html>
      <body>
        <WebVitals />
        {children}
      </body>
    </html>
  )
}

What Are Web Vitals?

Web Vitals are key performance metrics that reflect user experience:

TTFB – Time to First Byte
FCP – First Contentful Paint
LCP – Largest Contentful Paint
FID – First Input Delay
CLS – Cumulative Layout Shift
INP – Interaction to Next Paint

You can handle each metric using its name property:

useReportWebVitals((metric) => {
  switch (metric.name) {
    case 'FCP': {
      // handle FCP
    }
    case 'LCP': {
      // handle LCP
    }
    // ...
  }
})

Sending Metrics to External Services

To send metrics to a custom endpoint:

useReportWebVitals((metric) => {
  const body = JSON.stringify(metric)
  const url = 'https://example.com/analytics'

  if (navigator.sendBeacon) {
    navigator.sendBeacon(url, body)
  } else {
    fetch(url, { body, method: 'POST', keepalive: true })
  }
})

Integrating with Google Analytics

If you use Google Analytics, you can send metrics using window.gtag:

useReportWebVitals((metric) => {
  window.gtag('event', metric.name, {
    value: Math.round(
      metric.name === 'CLS' ? metric.value * 1000 : metric.value
    ),
    event_label: metric.id,
    non_interaction: true,
  })
})

Conclusion

Next.js provides powerful tools for performance tracking and analytics. With Web Vitals, instrumentation-client, and external reporting, you can monitor real user experience and optimize your application effectively.