Analytics

Core Idea

Meça e reporte métricas de performance (Web Vitals) usando o hook useReportWebVitals, ou instrumente analytics/tracking globais via instrumentation-client.js|ts, executado antes do código frontend da aplicação.

Key Concepts

• instrumentation-client.js|ts: arquivo na raiz do projeto que roda antes do frontend começar a executar; ideal para inicializar analytics, error tracking ou monitoring globais.
• useReportWebVitals (de next/web-vitals): hook client-only ('use client') que recebe uma callback chamada para cada métrica coletada.
• Web Vitals cobertos: TTFB, FCP, LCP, FID, CLS, INP.
• Padrão de isolamento: criar um componente WebVitals separado importado no root layout, para confinar o client boundary só a esse componente.

Code Examples

console.log('Analytics initialized')

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

• O que demonstra: Setup de error tracking global antes do app iniciar.

'use client'
import { useReportWebVitals } from 'next/web-vitals'

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

• O que demonstra: Tratamento por tipo de métrica usando metric.name.

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 })
  }
})

• O que demonstra: Envio de métricas a um endpoint externo, preferindo sendBeacon com fallback para fetch com keepalive.

Anti-patterns

• Chamar useReportWebVitals direto no root layout: como exige 'use client', isso expande o client boundary desnecessariamente; extraia para um componente WebVitals isolado.

Key Takeaways

1. Use useReportWebVitals para reportar Web Vitals manualmente, ou o serviço gerenciado da Vercel para coleta/visualização automática.
2. instrumentation-client.js|ts roda antes do app, ideal para setup global de analytics/error tracking.
3. Isole o hook em um componente client separado para não expandir o client boundary do layout inteiro.
4. Prefira navigator.sendBeacon para enviar métricas, com fallback para fetch(..., { keepalive: true }).
5. Para Google Analytics, o id da métrica permite construir distribuições/percentis manualmente.

Connects To

• use-report-web-vitals (API reference): referência completa da API do hook.
• instrumentation: guia mais amplo de instrumentação server-side, complementar ao client-side aqui.