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

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

Este error ocurre cuando el HTML generado por el servidor (SSR/SSG) no coincide con el árbol de React generado durante la primera renderización del cliente. Durante la hidratación, React espera que el DOM inicial coincida exactamente con el que generó el servidor; cualquier diferencia provoca este error crítico.

Causa raíz

La causa más frecuente en aplicaciones modernas es el uso de APIs del navegador (window, localStorage, Date.now(), etc.) directamente en el renderizado, lo que provoca que el contenido sea diferente entre SSR (donde no están disponibles) y CSR (donde sí lo están). Otras causas comunes incluyen:

Uso de typeof window !== 'undefined' en el cuerpo del componente (no dentro de useEffect)
Librerías CSS-in-JS mal configuradas (especialmente styled-components sin @emotion/react o @emotion/server)
Extensiones del navegador (como Dark Reader o ad blockers) que modifican el DOM
Metaetiquetas de detección automática en iOS (format-detection)
Minificación automática por CDN (Cloudflare Auto Minify)

Pasos para solucionarlo

✅ Paso 1: Identifica la fuente del desajuste

Busca en tu código:

Uso de Date, Math.random(), localStorage, window, navigator, etc.
Lógica condicional basada en typeof window fuera de hooks de efecto
Componentes que renderizan contenido dinámico sin protección

🔍 Tip rápido: Usa console.log('server' if !window else 'client') en el componente sospechoso y revisa el HTML fuente vs. el DOM del navegador.

✅ Paso 2: Aplica la solución según el caso

Caso A: Contenido dinámico (ej. fecha/hora actual, ID aleatorio)

Usa suppressHydrationWarning en el elemento específico:

// ✅ CORRECTO: Solo suprime advertencia en el elemento problemático
<time suppressHydrationWarning>{new Date().toLocaleDateString()}</time>

⚠️ Importante: No lo uses en contenedores grandes (como <div> que envuelve todo el contenido). Solo en elementos atómicos.

Caso B: Lógica condicional basada en entorno (ej. `window` o `localStorage`)

Mueve la lógica a useEffect + estado local:

import { useState, useEffect } from 'react';

export default function ClientOnlyComponent() {
  const [isClient, setIsClient] = useState(false);

  useEffect(() => {
    setIsClient(true);
  }, []);

  // ✅ SSR renderiza siempre el fallback; CSR renderiza lo real tras hidratación
  return (
    <div>
      {isClient ? (
        <div>
          <p>Contenido del navegador (ej. localStorage: {localStorage.getItem('theme')})</p>
        </div>
      ) : (
        <p>Cargando...</p> {/* Contenido idéntico en SSR y CSR inicial */}
      )}
    </div>
  );
}

Caso C: Componente que usa APIs del navegador (ej. `window.matchMedia`)

Desactiva SSR para ese componente con next/dynamic:

// components/ClientComponent.tsx
export default function ClientComponent() {
  const [width, setWidth] = useState(0);

  useEffect(() => {
    const handleResize = () => setWidth(window.innerWidth);
    window.addEventListener('resize', handleResize);
    handleResize(); // Inicializar
    return () => window.removeEventListener('resize', handleResize);
  }, []);

  return <p>Ancho: {width}px</p>;
}

// page.tsx
import dynamic from 'next/dynamic';

const ClientComponent = dynamic(() => import('../components/ClientComponent'), {
  ssr: false, // ✅ Evita renderizado en servidor
});

export default function Page() {
  return (
    <main>
      <h1>Página principal</h1>
      <ClientComponent />
    </main>
  );
}

Caso D: iOS convierte números/teléfonos en enlaces

Agrega metaetiqueta en <head> (en layout.tsx):

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

Caso E: Librerías CSS-in-JS (ej. `styled-components`)

Configura correctamente para SSR:

npm install @emotion/react @emotion/server

// app/layout.tsx
import { EmotionIntl } from '@emotion/react';
import { CacheProvider } from '@emotion/react';
import createCache from '@emotion/cache';

const cache = createCache({ key: 'css' });

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <head>
        <style
          data-emotion={`css ${cache.key}`}
          dangerouslySetInnerHTML={{ __html: '' }}
        />
      </head>
      <body>
        <CacheProvider value={cache}>{children}</CacheProvider>
      </body>
    </html>
  );
}

🔥 Alternativa recomendada: Usa @emotion/react directamente o styled-components con su configuración oficial para Next.js.

✅ Paso 3: Verifica configuraciones de CDN

Si usas Cloudflare:

Desactiva Auto Minify (HTML)
Desactiva Rocket Loader
Asegúrate de que Brotli no esté corrompiendo el HTML

🛠️ Prueba rápida: Despliega en entorno local sin CDN. Si el error desaparece, el problema está en la infraestructura.

Pro-tip: Diagnóstico profesional

Revisa el HTML fuente (Ctrl+U) y compáralo con el DOM del navegador (F12 > Elements).
Usa console.log('Hydration check:', window ? 'client' : 'server') en el componente sospechoso.
Activa React DevTools Profiler y busca componentes con hydrate en rojo.
En producción, usa suppressHydrationWarning solo como último recurso — nunca como solución principal.

💡 Regla de oro: Si el contenido cambia entre SSR y CSR, debe estar protegido con useEffect o ssr: false. El usuario nunca debe ver un "flash" de contenido diferente durante hidratación.

Aplica estos pasos en orden y el error desaparecerá. Si persiste, revisa logs de tu CDN y extensiones del navegador (prueba en modo incógnito).

🚀 ¿Quieres más soluciones técnicas?

Si te sirvió esta ayuda, suscríbete para recibir los errores más comunes de la semana y cómo evitarlos.
👉 Suscríbete aquí

推荐订阅源

DEV Community