So beheben Sie Hydrierungsinkonsistenzen durch KI-generierte React-Komponenten

KI-Agenten generieren React-Komponenten, die auf Server und Client unterschiedliches HTML rendern, was zu Hydrierungsfehlern und einer defekten Benutzeroberfläche beim ersten Laden führt.

Der Agent schreibt Komponenten, die auf dem Server und auf dem Client unterschiedliches HTML erzeugen – Daten, Zufallswerte, window-Prüfungen –, was dazu führt, dass React einen Hydrierungs-Mismatch-Fehler auslöst und den gesamten Baum beim Laden neu rendert.

Das Symptom

Eine Komponente liest Date.now(), Math.random() oder window während des Renderns und erzeugt dadurch auf Server- und Client-Seite unterschiedliche Ausgaben.

// WRONG — hydration mismatch
export function Timestamp() {
  return <p>Page loaded at: {new Date().toLocaleTimeString()}</p>;
  // Server renders "10:00:00 AM", client renders "10:00:01 AM" — mismatch
}

// WRONG — conditional on window
export function ThemeIcon() {
  const isDark = typeof window !== "undefined" && window.matchMedia("(prefers-color-scheme: dark)").matches;
  return <span>{isDark ? "🌙" : "☀️"}</span>;
  // Server: always renders "☀️"; client: may render "🌙" — mismatch
}

Die Browserkonsole zeigt:

Error: Hydration failed because the initial UI does not match what was rendered
on the server.

Warum es passiert

Der Agent schreibt Komponenten, die isoliert betrachtet korrekt erscheinen. Er simuliert keine zwei separaten Renderdurchläufe (SSR + Client-Hydrierung) und weiß nicht, dass jeder Wert, der zwischen beiden abweicht, die Hydrierung unterbricht.

Wie man es erkennt

Date.now(), new Date(), Math.random() werden direkt in JSX oder während des Renderns aufgerufen, ohne innerhalb eines useEffect oder useState-Initialisierers zu sein.
typeof window !== "undefined"-Abfragen innerhalb des Render-Rückgabewerts – der Server nimmt immer den false-Zweig.
localStorage, sessionStorage oder navigator werden während des Renderns gelesen.
Unterschiedliche HTML-Tags oder Attributwerte zwischen Server- und Client-Ausgabe (sichtbar in der React DevTools Hydrierungswarnung).

Wie man es behebt

Verschieben Sie nur im Browser verfügbare Werte in die Zeit nach dem Mount, oder erzeugen Sie stabile Werte auf dem Server und übergeben Sie sie als Props.

// CORRECT — defer client-only value to after mount
"use client";
import { useState, useEffect } from "react";

export function Timestamp() {
  const [time, setTime] = useState<string | null>(null);

  useEffect(() => {
    setTime(new Date().toLocaleTimeString());
  }, []);

  if (!time) return <p>Loading time…</p>; // matches server output
  return <p>Page loaded at: {time}</p>;
}

// CORRECT — theme icon: use CSS / data attribute, avoid JS render branch
// Set data-theme on <html> in a blocking inline script (not React)
// Then use CSS: [data-theme="dark"] .icon { content: "🌙" }

// Or use Next.js next-themes which handles SSR safely:
import { useTheme } from "next-themes";
import { useEffect, useState } from "react";

export function ThemeIcon() {
  const { resolvedTheme } = useTheme();
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  if (!mounted) return <span style={{ width: 24 }} />; // stable placeholder
  return <span>{resolvedTheme === "dark" ? "🌙" : "☀️"}</span>;
}

[ ] No Date.now() / Math.random() / new Date() called directly during render
[ ] No typeof window / localStorage / navigator accessed during render
[ ] Browser-only state initializes to null/undefined, set in useEffect
[ ] Render a stable placeholder (same as server output) until after mount
[ ] Use suppressHydrationWarning only on elements where the mismatch is intentional (e.g. timestamp)
[ ] Run "next build && next start" and check browser console for hydration errors

Fix-Prompt

This component causes a React hydration mismatch because it reads browser-only
values (Date, window, localStorage, Math.random) during render. Fix it: move
all browser-only reads into a useEffect that sets state after mount, render a
stable placeholder on first render that matches what the server produces, and
never conditionally return different JSX trees based on typeof window. Explain
why each change prevents the mismatch.

Test

# Build and start, then check for hydration errors with curl diff
next build 2>&1 | grep -i "hydrat\|mismatch" && echo "FAIL: hydration error in build" || echo "Build OK"

# Runtime: open browser console after next start and look for hydration warnings
next start &
sleep 3
curl -s http://localhost:3000 | grep -i "data-nextjs-scroll-focus-boundary" > /dev/null && echo "Server rendered OK"