Fix React Hydration Mismatches at the Source

1. Read the actual diff the error reports.

grep -o "server: .*" build/client/*.log 2>/dev/null | head -3 || echo "check devtools console: React prints server-rendered vs client-expected HTML fragments"

Expected output: React names the differing node and shows both fragments, for example a timestamp rendered as 14:03 on the server and 14:03:07 on the client.

2. Trace the divergent value to its render input.

// the classic sources, in order of frequency:

// 1. time
const now = new Date().toISOString();          // server time != client time

// 2. randomness
const id = Math.random().toString(36);          // different per process

// 3. environment
const isDev = process.env.NODE_ENV === 'development'; // can differ SSR vs browser

// 4. browser-only APIs during render
const width = window.innerWidth;                // crashes or undefined on server

Expected output: The source list maps each mismatch class to its fix: defer time to effect, seed randomness, gate browser APIs behind mounted state.

3. Fix by deferring the value to after mount, not by suppressing.

// before: mismatch on every load
function LastSync() {
  return <span>synced at {new Date().toLocaleTimeString()}</span>;
}

// after: stable server markup, fill in after mount
import { useEffect, useState } from 'react';

function LastSync() {
  const [at, setAt] = useState<string | null>(null);
  useEffect(() => {
    setAt(new Date().toLocaleTimeString());
    const t = setInterval(() => setAt(new Date().toLocaleTimeString()), 30_000);
    return () => clearInterval(t);
  }, []);
  return <span suppressHydrationWarning>{at ?? '…'}</span>;
}

Expected output: The server renders a stable placeholder, the effect fills the real time once, and the mismatch disappears because the first client render matches the server output.

4. For content that must differ, render deterministically and patch after.

// locale-dependent formatting: compute from a fixed source
// server and client agree on the raw value; only the format varies

function Price({ cents, currency }: { cents: number; currency: string }) {
  // Intl on server may use en-US; on client the visitor's locale
  // render with explicit locale, NOT the ambient one:
  const fmt = new Intl.NumberFormat('en-US', { style: 'currency', currency });
  return <span>{fmt.format(cents / 100)}</span>;
}

// if user-locale formatting is the product requirement:
function LocalPrice(props) {
  const [fmt, setFmt] = useState(new Intl.NumberFormat('en-US', { style: 'currency', currency: props.currency }));
  useEffect(() => {
    setFmt(new Intl.NumberFormat(navigator.language, { style: 'currency', currency: props.currency }));
  }, [props.currency]);
  return <span suppressHydrationWarning>{fmt.format(props.cents / 100)}</span>;
}

Expected output: Locale formatting is pinned to an explicit locale for the shared first render, then upgraded to the visitor locale after mount; the suppress scope covers one text node, not a subtree.

5. Verify the console is clean and no suppress calls were added carelessly.

rg -n "suppressHydrationWarning" src/ | wc -l; rg -n "suppressHydrationWarning" src/ | head -5; echo "then reload the page and confirm zero hydration warnings in console"

Expected output: A count near zero with each remaining instance justified by a deliberate post-mount patch, and a reload free of hydration errors.

Problem

Mismatch only appears in production, not dev

Solution

Dev double-render masks or reveals different paths; capture the production HTML with curl and run the client build against it locally to reproduce the exact divergence.

Problem

A third-party widget injects markup during render

Solution

Move the script into an effect with a ref container; vendor code that mutates the DOM during hydration is inherently nondeterministic and must be quarantined behind mount.

Problem

Invalid HTML nesting causes cascading mismatches

Solution

The browser reparents illegal nodes (a div inside p), so React compares a moved tree; fix the nesting first with the React error code as the guide, since later mismatches are noise until then.