리액트 하이드레이션은 SSR로 먼저 받은 HTML을 브라우저에서 React가 이어받아 클릭, 입력, 상태 변경이 되는 화면으로 만드는 과정입니다.
Next js 에러를 만났다면 화면이 왜 달라졌는지부터 좁혀야 합니다.
리액트 하이드레이션 기본 개념
리액트 하이드레이션은 서버 HTML에 이벤트와 상태를 연결하는 과정입니다.
React 공식 문서의 hydrateRoot는 이미 생성된 DOM에 React 컴포넌트 로직을 붙이고, 이후 DOM 관리를 React가 맡는 API입니다.
처음부터 화면을 새로 그리는 방식이 아닙니다.
핵심은 사용자가 서버에서 온 정적인 HTML을 먼저 본다는 점입니다.
JavaScript가 내려온 뒤 같은 구조에 클릭, 입력, 상태 변경 같은 상호작용이 이어집니다.
초보자는 hydrate를 단어 뜻으로만 외우기보다 정적인 HTML에 앱의 동작을 입히는 단계로 잡는 편이 덜 헷갈립니다.
React hydration이라는 영어 표현도 같은 맥락입니다.
SSR과 CSR 차이 기준
SSR은 HTML을 먼저 보내고, CSR은 브라우저에서 화면을 조립합니다.
웹 표준 자료를 다루는 MDN의 SSR 설명에서도 SSR은 서버가 HTML 내용을 만들어 클라이언트에 보내는 방식으로 구분합니다.
클라이언트 렌더링은 JavaScript 실행 뒤 화면 내용이 채워집니다.
CSR SSR 차이를 단순 속도 비교로만 보면 판단이 흐려집니다.
검색 노출, 첫 화면 표시, 개인화 데이터, 인터랙션 시점을 같이 봐야 합니다.
리액트 SSR에서는 서버가 JSX 결과를 HTML로 만들고, 브라우저가 같은 컴포넌트 트리를 다시 계산하며 이어 붙입니다.
이 부분은 로딩 속도보다 서버와 클라이언트의 첫 결과 일치가 더 중요합니다.
사용자별 시간, 랜덤 값, 브라우저 저장소 값이 첫 화면에 바로 섞이면 구조가 흔들립니다.
그래서 개인화 요소는 서버 데이터로 고정하거나, 첫 렌더 뒤에 따로 바꾸는 방식이 현실적입니다.
React 공식 문서하이드레이션 에러 원인
하이드레이션 에러는 서버 결과와 첫 브라우저 결과가 다를 때 납니다.
Next js 공식 오류 문서의 react-hydration-error는 잘못된 태그 중첩, typeof window 분기, localStorage 같은 브라우저 전용 API, 날짜와 시간 값, CSS in JS 설정 문제를 주요 원인으로 듭니다.
Next js hydration에서 자주 보이는 hydration mismatch는 텍스트 한 줄 차이로 시작해도 클릭 위치나 상태 보존에 영향을 줄 가능성이 있습니다.
조건만 보면 사소해 보여도 실제 사용감에서는 화면이 깜빡이거나 일부 이벤트가 어긋나는 식으로 드러납니다.
애매한 점은 모든 차이가 코드 버그만은 아니라는 데 있습니다.
브라우저 확장 프로그램, CDN의 HTML 변경, iOS 자동 링크 변환처럼 앱 바깥 요인도 있으니 먼저 재현 환경을 좁히는 것이 좋습니다.
반대로 특정 컴포넌트가 반드시 브라우저 값으로만 그려져야 한다면, SSR을 끄거나 첫 렌더에서는 빈 상태를 유지하는 선택지가 낫습니다.
리액트 하이드레이션 확인 순서
Next js의 hydration mismatch는 개발 콘솔과 오류 화면에서 먼저 봅니다.
확인 순서는 서버 HTML, 첫 클라이언트 렌더, 브라우저 전용 코드 순서가 편합니다.
Next js의 서버와 클라이언트 컴포넌트 문서는 기본적으로 layout과 page가 서버 컴포넌트이며, 상호작용이나 브라우저 API가 필요할 때 클라이언트 컴포넌트를 쓴다고 설명합니다.
리액트 하이드레이션 확인 순서에서 첫 번째는 HTML 태그 구조입니다. <p> 안에 <div>가 들어가거나 버튼 안에 버튼이 들어가는 형태는 Next js 에러의 원인이 되기 쉽습니다.
두 번째는 렌더 중 실행되는 값입니다. Date(), Math.random(), window, document, localStorage는 서버와 브라우저 결과를 다르게 만들기 쉬우므로 렌더 본문보다 useEffect 쪽으로 옮기는지 봐야 합니다.
세 번째는 라이브러리 설정입니다.
CSS in JS, 테마, 지역 시간대, 쿠키 기반 UI는 정상처럼 보여도 첫 렌더 결과가 달라질 수 있어 재현 코드로 줄여 확인하면 판단이 빨라집니다.
수정 전 체크와 성능 기준
수정 전에는 차이가 난 위치와 렌더링 환경을 먼저 나눠야 합니다.
무작정 use client를 붙이면 에러가 줄어드는 것처럼 보일 때가 있습니다.
대신 클라이언트 번들이 커지고 서버사이드 렌더링 장점이 줄어들 수 있으니 마지막 선택지로 두는 편이 낫습니다.
먼저 마크업 오류를 고치고, 그다음 브라우저 전용 값을 useEffect로 미룹니다.
시간처럼 차이가 불가피한 한 줄은 suppressHydrationWarning을 검토하되, React 문서처럼 남용하지 않는 기준이 필요합니다.
dynamic(..., { ssr: false })는 지도, 차트, 에디터처럼 브라우저 의존성이 큰 컴포넌트에 맞습니다.
목록, 상품명, 본문 텍스트처럼 검색과 첫 화면 가치가 큰 영역에는 쉽게 적용하지 않는 것이 좋습니다.
성능과 사용자 경험 기준은 빠른 첫 화면과 늦지 않은 상호작용의 균형입니다.
정보형 페이지는 SSR 유지가 맞고, 로그인 뒤 복잡한 도구 화면은 클라이언트 렌더링 비중을 높이는 쪽이 현실적입니다.
이런 사람에게는 SSR과 하이드레이션 구조를 유지하는 편이 맞습니다.
검색 유입, 공유 미리보기, 초기 로딩 안정성이 중요하다면 서버 결과를 고정하고 차이를 줄이는 방향으로 보세요.
반대로 브라우저 API가 화면의 대부분을 결정한다면 먼저 클라이언트 컴포넌트 경계를 다시 잡아야 합니다.
이 기준을 잡으면 임시 수정과 구조 수정이 구분됩니다.
핵심 요약
- 리액트 하이드레이션은 SSR HTML에 React 이벤트와 상태를 붙이는 단계입니다.
- 하이드레이션 에러는 서버 결과와 브라우저 첫 결과가 다를 때 시작됩니다.
Date(),Math.random(),window, 잘못된 태그 중첩을 먼저 확인합니다.- 해결은 마크업 수정,
useEffect이동, 필요한 경우 SSR 제외 순서로 봅니다. - 성능은 첫 화면 속도와 상호작용 준비 시간을 함께 기준으로 잡습니다.