Cómo solucionar el error \"Text content does not match se...

Cómo solucionar el error "Text content does not match server-rendered HTML" en Next.js

Este error ocurre cuando el HTML generado en el servidor (SSR) no coincide con el árbol de React que se construye durante la hidratación inicial en el navegador. Es un problema crítico que rompe la experiencia de usuario y puede causar comportamientos impredecibles.

Causa raíz

En tu caso, el error está relacionado con contenido dinámico que varía entre renderizado del servidor y renderizado del cliente, probablemente por:

Uso de Date() o new Date() en el renderizado (ej. fechas de eventos como JUN 9, JUN 11, etc.)
Uso de typeof window !== 'undefined' o APIs del navegador directamente en el render
Metaetiquetas o scripts que modifican el DOM antes de la hidratación (como iOS detectando fechas como enlaces)
Configuración incorrecta de librerías CSS-in-JS o Edge/CDN que modifiquen el HTML

Solución definitiva (pasos)

✅ Paso 1: Aisla el contenido dinámico con `suppressHydrationWarning`

Si el contenido que varía es intencional (como fechas de eventos), envuelve solo el elemento problemático con suppressHydrationWarning={true}:

// app/page.tsx o app/events/page.tsx
export default function EventsPage() {
  const events = [
    { name: 'NEXT.JS NIGHTS', date: new Date('2024-06-09') },
    { name: 'AMS', date: new Date('2024-06-11') },
    { name: 'LDN', date: new Date('2024-06-18') },
  ];

  return (
    <div>
      <h2>VIEW EVENTS</h2>
      <ul>
        {events.map((event, i) => (
          <li key={i}>
            <strong>{event.name}</strong>
            {/* ✅ Solo este elemento usa suppressHydrationWarning */}
            <time 
              dateTime={event.date.toISOString()} 
              suppressHydrationWarning
            >
              {event.date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' })}
            </time>
          </li>
        ))}
      </ul>
    </div>
  );
}

⚠️ Importante: suppressHydrationWarning solo funciona en el elemento inmediato, no en hijos. Usa span, time, div, etc., no en contenedores grandes.

✅ Paso 2: Evita `Date()` en el render (si no usas `suppressHydrationWarning`)

Si prefieres evitar suppressHydrationWarning, genera las fechas en el cliente solo:

// app/page.tsx
'use client';

import { useState, useEffect } from 'react';

export default function EventsPage() {
  const [events, setEvents] = useState<{ name: string; dateStr: string }[]>([]);

  useEffect(() => {
    const now = new Date();
    setEvents([
      { name: 'NEXT.JS NIGHTS', dateStr: 'JUN 9' },
      { name: 'AMS', dateStr: 'JUN 11' },
      { name: 'LDN', dateStr: 'JUN 18' },
    ]);
  }, []);

  return (
    <div>
      <h2>VIEW EVENTS</h2>
      <ul>
        {events.map((event, i) => (
          <li key={i}>
            <strong>{event.name}</strong> <span>{event.dateStr}</span>
          </li>
        ))}
      </ul>
    </div>
  );
}

🔥 Clave: Usa 'use client' y useState/useEffect para evitar que el servidor intente renderizar contenido dinámico.

✅ Paso 3: Deshabilita detección automática de iOS (si aplica)

Agrega esta metaetiqueta en app/layout.tsx para evitar que iOS convierta fechas en enlaces:

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <meta
          name="format-detection"
          content="telephone=no, date=no, email=no, address=no"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

✅ Paso 4: Verifica configuraciones de Edge/CDN

Si usas Cloudflare, Vercel Edge Functions, o CDN:

Cloudflare: Deshabilita Auto Minify (HTML) y Rocket Loader.
Vercel: Evita middleware que modifique el HTML (como next.config.js con headers que inyecten scripts).
Otros: Asegúrate de que no haya HTML rewriting en el path /app.

Pro-tip: Diagnóstico rápido

Reproduce en modo incógnito (para descartar extensiones).
Busca en el DOM el texto exacto que causa el mismatch (ej. "JUN 9").
Usa console.log(window) dentro de useEffect para confirmar que el código no se ejecuta en SSR.
Activa NEXT_TELEMETRY_DEBUG=1 para ver logs detallados de hidratación.

🛠️ Si el error persiste: Usa suppressHydrationWarning en el elemento más específico posible y nunca en <html>, <body> o <div> grandes.

✅ Solución final recomendada: Usa suppressHydrationWarning en el <time> o <span> que muestra la fecha, y asegúrate de que el atributo dateTime sea estático (ISO 8601). Esto garantiza accesibilidad y evita hidratación sin sacrificar UX.

推荐订阅源

DEV Community