DEV Community

Erick Eduardo Ramos
Erick Eduardo Ramos

Posted on

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

#nextjs #react #spanish #tutorial

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>
  );
}
Enter fullscreen mode Exit fullscreen mode

⚠️ 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>
  );
}
Enter fullscreen mode Exit fullscreen mode

🔥 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>
  );
}
Enter fullscreen mode Exit fullscreen mode

✅ 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

  1. Reproduce en modo incógnito (para descartar extensiones).
  2. Busca en el DOM el texto exacto que causa el mismatch (ej. "JUN 9").
  3. Usa console.log(window) dentro de useEffect para confirmar que el código no se ejecuta en SSR.
  4. 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.

Top comments (0)