Next.js suppressHydrationWarning 속성 이해하기
KUKJIN LEE • 1일 전 작성
suppressHydrationWarning이란 무엇인가?
suppressHydrationWarning은 React/Next.js에서 하이드레이션 경고(Hydration Warning)를 억제하기 위한 특별한 속성입니다. 서버 사이드 렌더링(SSR)된 내용과 클라이언트 사이드 렌더링(CSR)된 내용이 일치하지 않을 경우, React는 개발자에게 내용 불일치 경고를 표시합니다.
즉, 해당 요소의 서버 렌더링 결과와 클라이언트 초기 렌더링 결과가 달라도 React가 콘솔 경고를 출력하지 않도록 해주는 일종의 안전장치(escape hatch)입니다.
하지만 개발자가 불일치를 발생시키는 경우도 있습니다. 예를 들어, 현재 시간에 따라 변하는 데이터를 화면에 표시하는 경우 서버와 클라이언트의 출력이 달라지는 것은 피할 수 없습니다.
suppressHydrationWarning 속성이 바로 이러한 불가피한 불일치 상황에서 사용됩니다.
Hydration Warning은 언제 발생하나요?
Hydration 경고는 주로 SSR과 클라이언트 렌더링 결과가 달라질 때 발생합니다. 일반적인 React CSR에서는 처음에 빈 HTML을 보내고 모든 렌더링을 브라우저가 수행하기 때문에 이런 문제가 없지만, Next.js처럼 SSR을 활용하는 경우에는 상황이 다릅니다. SSR을 통해 서버에서 이미 완성된 HTML을 만든 뒤 클라이언트에서 이를 재사용하며 화면을 구성하는데, 이 과정에서 내용 차이가 있으면 React가 이를 감지해 경고를 출력합니다. 다음과 같은 경우에 이러한 불일치가 생길 수 있습니다.
- 시간이나 랜덤 값 등 매번 달라지는 데이터를 사용한 경우: 예를 들어 렌더링 시
Date()를 호출하여 현재 시간을 표시하거나,Math.random()으로 난수를 생성하면 서버에서 생성된 값과 브라우저에서 다시 생성된 값이 다를 수밖에 없습니다 -
잘못된 마크업 구조: HTML 태그를 잘못 중첩하거나 빠뜨린 경우에도 SSR/CSR 결과 차이로 경고가 발생할 수 있습니다 (예:
<table>내에<tbody>없이 바로<tr>을 넣는 경우 등). 이러한 마크업 불일치는 코드상의 버그이므로 우선 수정해야 합니다.
Hydration 경고는 개발자가 SSR 단계와 클라이언트 단계의 출력 일치성을 확인하고 잠재적인 버그를 잡을 수 있게 도와줍니다. 하지만 앞서 언급한 것처럼 의도된 차이도 경고로 표시되기 때문에, 실제 프로젝트에서는 상황에 따라 이 경고를 억제해야 할 필요가 있습니다. suppressHydrationWarning 속성은 바로 그런 상황에서 특정 요소에 한해서 경고를 무시하도록 해줍니다.
suppressHydrationWarning 사용하여 Hydration Warning 방지
// 현재 시각을 표시하는 React 컴포넌트 예제 (Next.js 페이지/컴포넌트에서 사용 가능)
function CurrentTime() {
// 현재 시각 문자열 생성 (SSR 시에도 실행됨)
const now = new Date().toLocaleTimeString(); // 예: "3:05:42 PM"
return (
<div>
{/* suppressHydrationWarning로 Hydration 경고를 방지 */}
현재 시각: <span suppressHydrationWarning>{now}</span>
</div>
);
}
export default CurrentTime;
"현재 시각: 3:05:42 PM"라는 HTML을 만들고, 브라우저가 이를 하이드레이션하면서 실제 현재 시각을 다시 계산하더라도(예: "현재 시각: 3:05:45 PM"으로 몇 초 차이로 달라진 경우) React가 그 차이에 대한 경고를 출력하지 않게 됩니다.
실제 프로젝트 활용 방법
실제 프로젝트에서 suppressHydrationWarning은 불가피하게 SSR과 클라이언트 결과가 달라지는 부분에 국한하여 사용됩니다. 몇 가지 활용 예시는 다음과 같습니다:
-
현재 시간/날짜 표시: 위에서 살펴본 예처럼 현재 시간, 오늘 날짜 등을 SSR 단계에서 출력하면 페이지 로드 시점에 약간의 차이가 생길 수 있습니다. 이때 해당 요소에
suppressHydrationWarning을 적용하면 경고를 숨길 수 있습니다. -
랜덤값 또는 고유 ID 출력: 예를 들어 페이지가 로드될 때마다 임의의 추천 문구나 고유한 ID를 생성해서 표시하는 경우, SSR vs 클라이언트 값 차이가 발생할 수 있습니다. 이러한 요소에 속성을 추가하면 마운트 시 경고 없이 값이 표시됩니다.
-
테마나 사용자 설정에 따른 초기 값 차이: 다크 모드처럼 초기 테마 설정이 SSR 단계와 클라이언트 단계에서 어긋날 수 있는 경우(
next-themes라이브러리 등 사용 시), 최상위<html>또는 특정 테마 관련 요소에suppressHydrationWarning을 사용하여 경고를 피할 수 있습니다.
이처럼 suppressHydrationWarning은 SSR 결과와 클라이언트 결과의 일시적인 불일치가 명확히 예상될 때 활용하면 유용합니다.
