Cómo solucionar el error Hydration Mismatch en aplicaciones de Next.js

✨ Respuesta Rápida

dentro de otro o ) Corregir la estructura DOM o desactivar SSR temporalmente con dynamic(() => ..., { ssr: false }) El error de hidratación en Next.js (Error: Hydration failed because the initial UI does not match what was rendered on the server) ocurre cuando el HTML renderizado por el servidor contiene valores dinámicos (tales como fechas con zonas horarias locales, números aleatorios o estados del objeto window) que cambian instantáneamente al cargarse en el navegador del cliente.

El Diagnóstico Rápido

Causa

Diferencia de renderizado entre el HTML generado en el servidor y el cliente React

Solución

Usar useEffect para renderizar datos dinámicos (ej. fechas, localStorage) solo en cliente

Causa

Etiquetas HTML anidadas incorrectamente (ej.

dentro de otro

o

)

Solución

Corregir la estructura DOM o desactivar SSR temporalmente con dynamic(() => ..., { ssr: false })

El error de hidratación en Next.js (Error: Hydration failed because the initial UI does not match what was rendered on the server) ocurre cuando el HTML renderizado por el servidor contiene valores dinámicos (tales como fechas con zonas horarias locales, números aleatorios o estados del objeto window) que cambian instantáneamente al cargarse en el navegador del cliente.

La Solución Paso a Paso

1. 1

   Paso 1: Identificar el nodo del DOM en conflicto en la consola de depuración

   Abre la consola de desarrollador de tu navegador (F12) al ocurrir el fallo. Next.js mostrará un reporte de inconsistencia detallando qué elemento HTML difiere entre el servidor y el cliente:

   PLAINTEXT Copiar

   # Alerta en la consola de depuración
   Warning: Text content did not match. Server: "08:30" Client: "14:30"
   

2. 2

   Paso 2: Utilizar un hook de estado para renderizar solo tras la hidratación

   Asegura que el componente que depende del estado local del cliente (como la zona horaria del sistema o el objeto localStorage) solo se renderice una vez que el componente se haya montado por completo en el navegador:

   JAVASCRIPT Copiar

   import { useState, useEffect } from 'react';
   
   export default function MiComponenteDinamico() {
     const [isClient, setIsClient] = useState(false);
   
     useEffect(() => {
       // Confirmar que el cliente está listo
       setIsClient(true);
     }, []);
   
     return (
       <div>
         {isClient ? new Date().toLocaleTimeString() : 'Cargando...'}
       </div>
     );
   }
   

3. 3

   Paso 3: Desactivar SSR de forma selectiva para componentes dinámicos

   Si necesitas omitir por completo el renderizado del lado del servidor para un componente que dependa de metadatos locales del cliente, utiliza la importación dinámica de Next.js:

   JAVASCRIPT Copiar

   import dynamic from 'next/dynamic';
   
   // Importar el componente dinámico desactivando el Server-Side Rendering
   const ComponenteSinSSR = dynamic(() => import('../components/MiReloj'), {
     ssr: false
   });