SSR & Hydration Markup

Introduction

SSR hydration markup is the discipline of making server-rendered HTML byte-identical to what the client framework expects before attach. Hydration mismatches cause React error #418, duplicated UI, and subtle SEO bugs when crawlers see different text than users after JS runs. Staff engineers treat SSR HTML as a tested artifact, not an implementation detail.

Business problem

Business pressure: Personalization SSR showed stale prices until hydrate — support refunds. Or hydration double-rendered reviews — trust metrics dropped. Correct SSR markup protects revenue and brand on first paint.

• Trust: Users compare view-source to screen — mismatches feel like fraud.
• SEO: Crawlers may index SSR HTML without running hydrate fixes.
• Perf: Failed hydrate triggers client re-render — wasted main-thread work.

Why this feature exists

Platform motivation: SSR delivers fast meaningful HTML; hydration reconnects event listeners and state. Without markup discipline, teams get the cost of both SSR and client re-render.

• History: Universal React → streaming SSR → RSC reducing hydrate surface.
• Alternative rejected: suppressHydrationWarning as default — hides bugs.
• Modern role: Selective hydrate and server components shrink mismatch risk.

Browser internals

Inside the engine: Browser paints SSR HTML immediately. Hydration JS walks DOM expecting structure matching virtual DOM. Text node whitespace, random IDs, Date/time locale, and browser-only APIs in render cause mismatches.

• Text nodes: Whitespace between tags matters in React 18 hydrate.
• Attributes: Boolean attributes serialized differently server vs client.
• Comments: Frameworks insert marker comments — do not strip in CDN HTML minifier.

Rendering workflow

Rendering path: Request → server render HTML string → TTFB → browser paint → download JS → hydrate → interactive. Streaming SSR sends early chunks; hydrate may start before full document arrives.

• Streaming: Suspense boundaries flush HTML — hydrate per segment.
• Deferred: Defer hydrate until idle for below-fold (experimental patterns).

Feature deep dive

Hydration-safe patterns: Same data on server and client first paint; no window/document in initial render; stable keys; suppress only documented browser extensions noise.

• Data: Embed JSON in <script type="application/json" id="__DATA__"> — parse client-side.
• Time: Format dates on server with fixed locale or hydrate after mount.
• IDs: useId() — not Math.random in render.

<!-- Server HTML -->
<div id="root">
  <main><h1>Hello, Ada</h1><p>3 items</p></main>
</div>
<script id="__DATA__" type="application/json">
{"user":"Ada","count":3}
</script>
<script type="module" src="/entry.client.js"></script>
<!-- Client must render identical h1/p before adding listeners -->

Accessibility analysis

A11y architecture: SSR HTML must be operable before hydrate for links and native form controls. Custom widgets need same ARIA in SSR and client first pass — do not add roles only after hydrate.

• Focus: Do not auto-focus in SSR unless intentional — duplicate focus on hydrate hurts.
• Live regions: Empty on SSR; populate after hydrate with consistent ids.

SEO impact

SEO architecture: Google often indexes SSR HTML. If client hydrate rewrites title or main text, you may create cloaking suspicion or inconsistent snippets. Keep primary content stable across hydrate.

• Price/stock: Must match structured data in SSR HTML.
• Hidden client-only content: Do not swap h1 text on hydrate for keywords.

Security considerations

Security boundary: Embedded hydration data must escape JSON for script context — U+2028/U+2029, </script> breaks. Use safe serialization helpers.

• XSS: User names in SSR HTML must be encoded — hydrate does not fix injection.
• CSP: Inline __DATA__ script may need nonce — align server template with CSP header.

Performance impact

Performance: Hydration is main-thread work proportional to component count. Reduce hydrate root; use islands or RSC. HTML minifiers that reorder attributes break hydrate — configure carefully.

• TBT: Large hydrate blocks INP until complete — prioritize above-fold interactive widgets only.
• Streaming: Early flush improves FCP; hydrate when segments arrive.

Real production example

Production pattern: Next.js App Router with RSC for static body, client component for cart only. CI runs renderToString snapshot vs Playwright outerHTML after hydrate — diff must be empty for Tier-0 routes.

• Monitoring: Log hydrate mismatch errors to Sentry with route and release.
• CDN: Disable HTML rewrite that strips comment markers.

Enterprise usage

Enterprise: SSR template service shared across brands — hydration checklist in PR template. Locale and timezone rendered from request headers consistently.

• Testing: Visual + DOM snapshot in staging per locale matrix.

Common production failures

What breaks in prod: Browser extension modifies DOM before hydrate — React crashes. CDN HTML optimizer collapsed whitespace — mass mismatch. Client used local timezone in Date — SSR UTC.

• Incident: A/B banner random id in SSR — hydrate fail rate 8%; fixed with deterministic seed.
• SEO: Client-only price update — structured data stale; aligned SSR and JSON-LD.

Architecture review questions

• Does client first render match SSR HTML byte-for-byte in contract tests?
• Is all render-time data available on server without window?
• Are HTML minification/CDN rules hydration-safe?
• How are mismatch errors monitored in production?

Hands-on project

Project: SSR a product page with embedded JSON data; hydrate with vanilla JS attachEventListeners. Introduce intentional mismatch; fix with stable render.

• Deliverable: server template, client entry, snapshot test script.

Interview questions

Try it yourself

Edit the HTML, CSS, or JS panels — the preview updates as you type.

Summary

SSR and hydration markup engineering ensures server HTML matches client expectations before attach. Teams embed data safely, avoid non-deterministic render, configure CDN/minifiers for framework markers, and monitor mismatch errors in production.