useReportWebVitals

useReportWebVitals 훅을 사용하면 Core Web Vitals를 보고할 수 있으며, 분석 서비스와 함께 사용할 수 있습니다.

app/_components/web-vitals.js

"use client";
 
import { useReportWebVitals } from "next/web-vitals";
 
export function WebVitals() {
  useReportWebVitals((metric) => {
    console.log(metric);
  });
}

app/layout.js

import { WebVitals } from "./_components/web-vitals";
 
export default function Layout({ children }) {
  return (
    <html>
      <body>
        <WebVitals />
        {children}
      </body>
    </html>
  );
}

useReportWebVitals 훅은 "use client" 지시문이 필요하므로, 루트 레이아웃이 가져오는 별도의 컴포넌트를 만드는 것이 가장 성능이 좋은 접근 방식입니다. 이는 클라이언트 경계를 WebVitals 컴포넌트에만 국한시킵니다.

useReportWebVitals

훅의 인자로 전달되는 metric 객체는 다음과 같은 속성들로 구성됩니다:

id: 현재 페이지 로드 과정에서 메트릭을 식별하는 고유 값
name: 성능 메트릭의 이름. 가능한 값에는 웹 애플리케이션에 특정한 Web Vitals 메트릭 이름(TTFB, FCP, LCP, FID, CLS)이 포함됩니다.
delta: 메트릭의 현재 값과 이전 값의 차이. 이 값은 일반적으로 밀리초 단위이며 시간에 따른 메트릭 값의 변화를 나타냅니다.
entries: 메트릭과 관련된 Performance Entries 배열. 이 항목들은 메트릭과 관련된 성능 이벤트에 대한 자세한 정보를 제공합니다.
navigationType: 메트릭 수집을 트리거한 내비게이션 유형을 나타냅니다. 가능한 값에는 "navigate", "reload", "back_forward", "prerender"가 있습니다.
rating: 메트릭 값에 대한 정성적 평가로, 성능 평가를 제공합니다. 가능한 값은 "good", "needs-improvement", "poor"입니다. 평가는 일반적으로 메트릭 값을 허용 가능하거나 최적화되지 않은 성능을 나타내는 사전 정의된 임계값과 비교하여 결정됩니다.
value: 성능 항목의 실제 값 또는 지속 시간으로, 일반적으로 밀리초 단위입니다. 이 값은 메트릭이 추적하는 성능 측면의 정량적 측정을 제공합니다. 값의 출처는 측정되는 특정 메트릭에 따라 다르며 다양한 Performance API에서 가져올 수 있습니다.

Web Vitals

Web Vitals는 웹 페이지의 사용자 경험을 캡처하는 데 목표를 둔 유용한 메트릭 집합입니다. 다음의 웹 바이탈이 모두 포함됩니다:

name 속성을 사용하여 이러한 모든 메트릭의 결과를 처리할 수 있습니다.

app/components/web-vitals.tsx

"use client";
 
import { useReportWebVitals } from "next/web-vitals";
 
export function WebVitals() {
  useReportWebVitals((metric) => {
    switch (metric.name) {
      case "FCP": {
        // FCP 결과 처리
      }
      case "LCP": {
        // LCP 결과 처리
      }
      // ...
    }
  });
}

app/components/web-vitals.js

"use client";
 
import { useReportWebVitals } from "next/web-vitals";
 
export function WebVitals() {
  useReportWebVitals((metric) => {
    switch (metric.name) {
      case "FCP": {
        // FCP 결과 처리
      }
      case "LCP": {
        // LCP 결과 처리
      }
      // ...
    }
  });
}

Vercel에서의 사용

Vercel Speed Insights는 useReportWebVitals를 사용하지 않고 대신 @vercel/speed-insights 패키지를 사용합니다. useReportWebVitals 훅은 로컬 개발에서 유용하거나 Web Vitals를 수집하기 위해 다른 서비스를 사용하는 경우에 유용합니다.

외부 시스템으로 결과 보내기

사이트에서 실제 사용자 성능을 측정하고 추적하기 위해 결과를 모든 엔드포인트로 보낼 수 있습니다. 예를 들어:

useReportWebVitals((metric) => {
  const body = JSON.stringify(metric);
  const url = "https://example.com/analytics";
 
  // 가능한 경우 `navigator.sendBeacon()`을 사용하고, 그렇지 않으면 `fetch()`로 대체합니다.
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url, body);
  } else {
    fetch(url, { body, method: "POST", keepalive: true });
  }
});

알아두면 좋은 점: Google Analytics를 사용하는 경우, id 값을 사용하면 수동으로 메트릭 분포를 구성할 수 있습니다 (백분위수 계산 등).

useReportWebVitals(metric => {
  // Google Analytics를 이 예제처럼 초기화했다면 `window.gtag`를 사용하세요:
  // https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics/pages/_app.js
  window.gtag('event', metric.name, {
    value: Math.round(metric.name === 'CLS' ? metric.value * 1000 : metric.value), // 값은 정수여야 합니다
    event_label: metric.id, // 현재 페이지 로드에 고유한 id
    non_interaction: true, // 이탈률에 영향을 주지 않습니다.
  });
}

Google Analytics로 결과 보내기에 대해 자세히 알아보세요.

usePathname useRouter