Comment configurer les analyses

Next.js dispose d'un support intégré pour mesurer et rapporter les métriques de performance. Vous pouvez soit utiliser le hook useReportWebVitals pour gérer vous-même le reporting, soit utiliser le service managé de Vercel qui collecte et visualise automatiquement les métriques pour vous.

Instrumentation côté client

Pour des besoins plus avancés en analyse et monitoring, Next.js fournit un fichier instrumentation-client.js|ts qui s'exécute avant le code frontend de votre application. C'est idéal pour configurer des outils globaux d'analyse, de suivi d'erreurs ou de monitoring de performance.

Pour l'utiliser, créez un fichier instrumentation-client.js ou instrumentation-client.ts à la racine de votre application :

// Initialiser l'analyse avant le démarrage de l'app
console.log('Analyse initialisée')

// Configurer le suivi global des erreurs
window.addEventListener('error', (event) => {
  // Envoyer à votre service de suivi d'erreurs
  reportError(event.error)
})

Implémentation personnalisée

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

function MyApp({ Component, pageProps }) {
  useReportWebVitals((metric) => {
    console.log(metric)
  })

  return <Component {...pageProps} />
}

Consultez la Référence API pour plus d'informations.

Web Vitals

Les Web Vitals sont un ensemble de métriques utiles qui visent à capturer l'expérience utilisateur d'une page web. Les Web Vitals suivants sont inclus :

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

Vous pouvez traiter tous les résultats de ces métriques en utilisant la propriété name.

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

function MyApp({ Component, pageProps }) {
  useReportWebVitals((metric) => {
    switch (metric.name) {
      case 'FCP': {
        // traiter les résultats FCP
      }
      case 'LCP': {
        // traiter les résultats LCP
      }
      // ...
    }
  })

  return <Component {...pageProps} />
}

Métriques personnalisées

En plus des métriques principales listées ci-dessus, il existe des métriques personnalisées supplémentaires qui mesurent le temps nécessaire à l'hydratation et au rendu de la page :

• Next.js-hydration : Temps nécessaire pour que la page démarre et termine son hydratation (en ms)
• Next.js-route-change-to-render : Temps nécessaire pour qu'une page commence à s'afficher après un changement de route (en ms)
• Next.js-render : Temps nécessaire pour qu'une page termine de s'afficher après un changement de route (en ms)

Vous pouvez traiter les résultats de ces métriques séparément :

export function reportWebVitals(metric) {
  switch (metric.name) {
    case 'Next.js-hydration':
      // traiter les résultats d'hydratation
      break
    case 'Next.js-route-change-to-render':
      // traiter les résultats de changement de route vers rendu
      break
    case 'Next.js-render':
      // traiter les résultats de rendu
      break
    default:
      break
  }
}

Ces métriques fonctionnent dans tous les navigateurs supportant l'API User Timing.

Envoi des résultats à des systèmes externes

Vous pouvez envoyer les résultats à n'importe quel endpoint pour mesurer et suivre les performances réelles des utilisateurs sur votre site. Par exemple :

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

  // Utiliser `navigator.sendBeacon()` si disponible, sinon `fetch()`.
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url, body)
  } else {
    fetch(url, { body, method: 'POST', keepalive: true })
  }
})

Bon à savoir : Si vous utilisez Google Analytics, utiliser la valeur id vous permet de construire manuellement des distributions de métriques (pour calculer des percentiles, etc.)

useReportWebVitals((metric) => {
  // Utiliser `window.gtag` si vous avez initialisé Google Analytics comme dans cet exemple :
  // https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics
  window.gtag('event', metric.name, {
    value: Math.round(
      metric.name === 'CLS' ? metric.value * 1000 : metric.value
    ), // les valeurs doivent être des entiers
    event_label: metric.id, // id unique au chargement de la page actuelle
    non_interaction: true, // évite d'affecter le taux de rebond.
  })
})

En savoir plus sur l'envoi de résultats à Google Analytics.