¿Qué es el error Hydration Failed en Next.js?
El error de hidratación (Hydration Failed) es uno de los problemas más comunes al desarrollar aplicaciones web utilizando frameworks de renderizado del lado del servidor (SSR) como Next.js. Ocurre cuando la estructura HTML generada por el servidor no coincide exactamente con la primera representación (render) realizada en el navegador del cliente.
Causas principales del error de hidratación
- Uso de funciones que devuelven valores dinámicos diferentes en cada ejecución, como
Math.random()onew Date(). - Manipulación del DOM o lectura del objeto
windowolocalStoragedirectamente durante la renderización inicial. - Extensiones de navegador que inyectan atributos o elementos HTML adicionales en el body antes de que se complete la carga.
- Etiquetas HTML mal anidadas, como colocar un elemento
<p>dentro de otro<p>o un<div>dentro de un<p>.
Método 1: Aislar el renderizado del lado del cliente
Si tu componente depende de APIs del navegador como window o localStorage, debes asegurarte de que solo se renderice después de que el componente haya sido montado en el cliente.
- Importa
useStateyuseEffectdesde React. - Crea una variable de estado booleana llamada
isMountedinicializada enfalse. - Actualiza el estado a
truedentro de unuseEffectvacío. - Retorna un marcador de posición (placeholder) o
nullsiisMountedes falso.
Ejemplo de código:
import { useState, useEffect } from 'react';
export default function ClientOnlyComponent() {
const [isMounted, setIsMounted] = useState(false);
useEffect(() => {
setIsMounted(true);
}, []);
if (!isMounted) {
return null;
}
return <div>{window.innerWidth}px</div>;
}Método 2: Deshabilitar el SSR temporalmente para componentes específicos
Si un componente externo o librería de terceros causa conflictos con la hidratación, puedes importarlo dinámicamente deshabilitando el renderizado del lado del servidor.
- Utiliza la función
dynamicprovista por Next.js. - Importa tu componente configurando la opción
ssr: false.
Ejemplo de código:
import dynamic from 'next/dynamic';
const HeavyComponent = dynamic(() => import('../components/HeavyComponent'), {
ssr: false,
});
export default function Page() {
return (
<main>
<HeavyComponent />
</main>
);
}Método 3: Corregir el anidamiento HTML inválido
Revisa la consola de desarrollo de tu navegador para identificar advertencias previas sobre HTML inválido. Los navegadores corrigen automáticamente estructuras incorrectas al cargar la página en el cliente, lo que rompe la sincronización con el DOM virtual del servidor.
- Busca etiquetas de bloque (como
<div>o<p>) anidadas incorrectamente. - Valida tus componentes principales utilizando herramientas de validación de HTML o revisando el árbol de elementos.