How does Next.js handle hydration? What is a hydration mismatch, and how do you debug it?

Question

Accepted Answer

Hydration is the process where React takes over the static HTML that was pre-rendered by Next.js on the server and makes it interactive by attaching event handlers and state. Next.js pre-renders every page by default, generating HTML in advance for better performance and SEO. When the browser loads this HTML, it's immediately visible to the user. Then, React's hydration step runs in the background, attaching event listeners and reconciling the component tree with the existing DOM. In Next.js 14+ with the App Router, only Client Components actually hydrate—Server Components are rendered entirely on the server and don't send JavaScript to the client, significantly reducing the amount of hydration work required. Definition: A hydration mismatch occurs when the HTML generated on the server differs from what React renders during the first render on the client. React expects the initial client render to perfectly match the server HTML to be able to attach event handlers efficiently. Warning symptoms: The browser console shows warnings like 'Text content did not match server-rendered HTML' and React attempts to recover, but this recovery process can be costly for performance. Impact: Mismatches force React to discard the server HTML and re-render on the client, causing layout shifts, lost CSS, and degraded user experience. // ❌ This causes a hydration mismatch export default function Home() { const [data, setData] = useState(''); useEffect(() => { fetch('/api/message') .then(res => res.json()) .then(json => setData(json.message)); }, []); return

{data}

; // Server renders "", client renders after fetch } // ✅ Fix: Use server component for initial data export default async function Home() { const res = await fetch('https://example.com/api/message', { cache: 'no-store' }); const { message } = await res.json(); return

{message}

; // Same on server and client } // ✅ Alternative: Consistent placeholder function Home() { const [data, setData] = useState('Loading...'); // Same initial value on both useEffect(() => { fetch('/api/message') .then(res => res.json()) .then(json => setData(json.message)); }, []); return

{data}

; // Escape hatch } Browser-only APIs: Using window, localStorage, or document in component rendering without checking if code runs on the server. Dynamic data without server rendering: Fetching data client-side with useState/useEffect but having no initial server-rendered value. Time-dependent content: Using Date() or Math.random() directly in render, producing different values on server vs client. Incorrect HTML nesting: Placing block elements inside

tags, nested tags, or other invalid HTML structures. Browser extensions modifying DOM: Some extensions inject elements or modify content, causing client HTML to differ from server. CSS Modules with lazy loading: Next.js may fail to include CSS for lazily-loaded components in the initial bundle, causing a flash of unstyled content during hydration. iOS format detection: iOS automatically converts phone numbers and dates to links, altering the HTML structure. Next.js provides several tools to help debug hydration issues. The development server shows detailed error messages pointing to the component tree where the mismatch occurs. Using React 18.2+ ensures you get the best hydration mismatch warnings with component stack traces. The Next.js Dev Tools extension can highlight exactly which elements differ. For production debugging, you can compare the server-rendered HTML (view page source) with the client DOM (inspect element) to identify discrepancies. Look for the specific element where the content differs and trace back to its component logic. 1. Read the console error carefully: The error message often includes the exact text that mismatched and points to the component. 2. Check your component tree: Identify which component contains the mismatched content by looking at the stack trace. 3. Compare server and client output: Run a production build locally with next build && next start to test the exact behavior. 4. Isolate browser extensions: Test in incognito mode or with extensions disabled to rule out DOM modifications. 5. Add suppression strategically: Use suppressHydrationWarning only for intentionally different content like timestamps. React 18+ introduced selective hydration, allowing you to wrap less important components in Suspense to defer their hydration. This improves perceived performance by prioritizing critical UI. However, selective hydration with CSS Modules can cause Flash of Unstyled Content (FOUC) if Next.js fails to include the CSS in the initial bundle. The component's HTML is correctly server-rendered with the proper class name, but the CSS loads lazily with the component, causing a visual flash when hydration completes. This issue particularly affects Pages Router with React.lazy and Suspense, and forces developers to c

How does Next.js handle hydration? What is a hydration mismatch, and how do you debug it?

Next.js pre-renders HTML on the server, then React hydrates it on the client to add interactivity; a hydration mismatch occurs when the server and client HTML differ, causing React to warn or fail

How does Next.js handle hydration? What is a hydration mismatch, and how do you debug it?

Next.js pre-renders HTML on the server, then React hydrates it on the client to add interactivity; a hydration mismatch occurs when the server and client HTML differ, causing React to warn or fail

Scenario Questions

Follow-up Questions