2nd/10_Wiki/Topics/Frontend/Hydration-Mismatch-and-SSR-Debugging.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-hydration-mismatch-and-ssr-debug	Hydration Mismatch and SSR Debugging	10_Wiki/Topics	verified	self	Hydration Mismatch SSR Debug Hydration Error	none	A	0.9	applied	react ssr hydration debugging		2026-05-10	pending	language framework typescript react-next

Hydration Mismatch and SSR Debugging

매 한 줄

"매 server-rendered HTML 과 매 client first render 가 매 다르면 매 React 가 매 throw — 매 일관된 input 이 매 핵심.". 매 typical 원인: Date.now / Math.random / window 접근 / locale / 매 third-party DOM 조작. React 19 부터 매 error message 가 매 어떤 attribute 가 매 mismatch 인지 매 정확히 표시.

매 핵심

매 원인 분류

• Time / random: server 의 매 시각 ≠ client 의 매 시각.
• Locale / timezone: Intl.DateTimeFormat 의 매 다른 결과.
• Window / document: server 에 매 없음.
• User-agent branching: useragent 의 매 다른 처리.
• Third-party script: AdSense, Cookiebot 의 매 DOM 변경.
• Browser extension: Grammarly, Dark Reader 의 매 inject.
• Conditional rendering on typeof window: 매 안티패턴.

매 React 의 매 행동 (19)

• 매 mismatch detection — 매 server HTML 을 매 polluted attribute 로 매 표시.
• 매 partial recovery — 매 mismatch boundary 만 매 client re-render.
• 매 보존되는 attribute (data-, aria-, custom): 매 dev warning.

매 Debug 도구

• Next.js: ?_rsc_no_cache 로 매 server payload 확인. next dev 의 매 colored diff.
• React DevTools: Profiler — hydration milestone.
• Browser: 매 view-source vs DOM inspect 비교.

매 응용

1. e-commerce — 매 product price (locale), cart count (cookie).
2. Auth — 매 logged-in / logged-out 분기.
3. A/B test — 매 server vs client variant 의 매 일치.

💻 패턴

Detect mismatch source (Next.js 15)

// Bad — Date.now() differs
function Now() { return <span>{Date.now()}</span>; }

// Good — pass server time as prop, render same on both
function Now({ serverTime }: { serverTime: number }) {
  return <span suppressHydrationWarning>{new Date(serverTime).toISOString()}</span>;
}

useEffect for client-only side effects

function ClientGreeting() {
  const [name, setName] = useState<string | null>(null);
  useEffect(() => setName(localStorage.getItem('name')), []);
  if (!name) return null;          // server returns null, client fills after mount
  return <p>Hi {name}</p>;
}

dynamic() with ssr: false (Next.js)

import dynamic from 'next/dynamic';
const Chart = dynamic(() => import('./Chart'), { ssr: false });
// Renders nothing on server, only on client

Avoid Math.random in render

// Bad
function Card() { return <div data-id={Math.random()}>...</div>; }

// Good — useId
function Card() { const id = useId(); return <div id={id}>...</div>; }

suppressHydrationWarning (last resort)

<time dateTime={iso} suppressHydrationWarning>
  {new Intl.DateTimeFormat('ko').format(new Date(iso))}
</time>

Diagnose third-party DOM mutation

useEffect(() => {
  const obs = new MutationObserver(records => {
    for (const r of records) {
      console.warn('mutation', r.target, r.attributeName, r.addedNodes);
    }
  });
  obs.observe(document.body, { subtree: true, childList: true, attributes: true });
  return () => obs.disconnect();
}, []);

Locale-stable rendering

// Server and client must agree — pass timezone explicitly
const fmt = new Intl.DateTimeFormat('ko-KR', { timeZone: 'Asia/Seoul' });
return <span>{fmt.format(new Date(props.iso))}</span>;

Replay server HTML offline

# Capture server HTML
curl -s https://app.example.com/page > server.html
# Open in fresh browser, compare with hydrated DOM via outerHTML diff

React 19 onRecoverableError

hydrateRoot(document, <App />, {
  onRecoverableError(err, info) {
    fetch('/log/hydration-error', {
      method: 'POST',
      body: JSON.stringify({ msg: String(err), digest: info.digest }),
    });
  },
});

매 결정 기준

원인	Fix
매 time / random	useId / passed-down server value
매 locale / TZ	매 explicit Intl 의 매 timeZone
매 window / localStorage	매 useEffect 후 setState
매 SSR 무가치 component	매 dynamic ssr:false
매 third-party inject	매 suppressHydrationWarning + 매 root 외부
매 extension (Grammarly)	매 무시 — 매 알려진 false positive

기본값: 매 server / client 를 매 동일 input 으로 매 강제. 매 last resort suppressHydrationWarning.

🔗 Graph

• 부모: Hydration · SSR
• 변형: Selective Hydration · Streaming SSR
• 응용: Next.js App Router · Remix · Astro
• Adjacent: useId · useEffect · React 19

🤖 LLM 활용

언제: 매 hydration error stack 분석, 매 SSR 코드 review, 매 timezone bug 진단. 언제 X: 매 pure CSR — 매 hydration 자체 X.

❌ 안티패턴

• typeof window !== 'undefined' in render: 매 server / client output 차이 — 매 mismatch 보장.
• Date.now() in render: 매 항상 mismatch.
• suppressHydrationWarning 남발: 매 진짜 bug 숨김.
• try/catch around hydrateRoot 만: 매 root cause 추적 X.

🧪 검증 / 중복

• Verified (React 19 docs — Hydration Errors, Next.js 15 docs).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — 매 mismatch 원인 + Next.js 15 debug