¿Qué es el error Hydration Failed en Next.js?
El error Hydration Failed o desajuste de hidratación ocurre en aplicaciones de React y Next.js cuando el marcado HTML generado por el servidor (SSR) no coincide exactamente con el HTML renderizado inicialmente en el navegador del cliente durante el primer render. Esto genera advertencias en la consola y puede romper la interactividad de los componentes afectados.
Principales causas del error de hidratación
Este problema suele ser provocado por discrepancias sutiles entre lo que el servidor procesa y lo que el cliente visualiza. Las causas más comunes incluyen:
- Uso de funciones que devuelven valores dinámicos como
new Date(),Math.random()o contadores basados en el tiempo sin control previo. - Extensiones del navegador que modifican el DOM antes de que React complete su proceso de hidratación.
- Estructuras HTML inválidas (por ejemplo, etiquetas de bloque
<div>anidadas incorrectamente dentro de párrafos<p>). - Lectura directa de objetos globales del navegador como
windowolocalStoragedurante la fase de renderizado inicial.
Método 1: Aislar el renderizado del lado del cliente
Si dependes de APIs del navegador o estados que cambian constantemente, debes asegurarte de que el componente solo se renderice en el cliente utilizando un estado booleano o desactivando el SSR.
- Crea un estado para verificar si el componente ya se ha montado:
const [isMounted, setIsMounted] = useState(false); - Actualiza el estado dentro del hook
useEffect:useEffect(() => { setIsMounted(true); }, []); - Condiciona el retorno del componente:
if (!isMounted) return null;
Método 2: Corregir discrepancias de fecha u hora
Si muestras marcas de tiempo que varían entre la zona horaria del servidor y la del cliente, se producirá un error de hidratación.
Para solucionarlo, formatea las fechas utilizando un enfoque similar al Método 1 o utiliza librerías que manejen el renderizado diferido hasta que el componente esté completamente montado en el navegador del usuario.
Método 3: Desactivar SSR en componentes específicos dinámicos
Next.js permite importar componentes dinámicamente desactivando el renderizado del servidor mediante next/dynamic.
Implementa la importación dinámica de la siguiente manera en tu archivo:
const DynamicComponent = dynamic(() => import('../components/MiComponente'), { ssr: false });Esta técnica es ideal para widgets complejos, mapas o gráficos interactivos que dependen fuertemente del DOM y causan conflictos en la hidratación.