¿Qué es el Error Hydration Failed y por qué ocurre?
El error de hidratación (Hydration Failed) es uno de los problemas más comunes al desarrollar aplicaciones web modernas utilizando renderizado del lado del servidor (SSR) con frameworks como Next.js o Remix. Ocurre cuando el HTML generado en el servidor no coincide exactamente con el primer renderizado que realiza el cliente en el navegador.
Principales causas de la falta de coincidencia en la hidratación
- Uso de funciones que devuelven valores dinámicos en el cliente pero estáticos en el servidor, como
new Date()oMath.random(). - Extensiones del navegador que modifican el DOM antes de que React complete el proceso de hidratación.
- Estructuras HTML inválidas (por ejemplo, etiquetas
panidadas dentro de otras etiquetaspodivdentro dep).
Método 1: Usar useEffect para renderizar contenido exclusivo del cliente
La forma más limpia de evitar discrepancias es asegurar que el código dependiente del navegador solo se ejecute después del montaje inicial utilizando el hook useEffect.
Modifica tu componente de la siguiente manera:
const [isClient, setIsClient] = useState(false); useEffect(() => { setIsClient(true); }, []); return ( <div> {isClient ? <p>Fecha actual: {new Date().toLocaleDateString()}</p> : <p>Cargando...</p>} </div> );Método 2: Deshabilitar temporalmente el SSR para componentes específicos
Si estás utilizando un componente que depende fuertemente de APIs del navegador (como window o localStorage) y no necesitas que sea indexado por SEO, puedes deshabilitar el renderizado del lado del servidor en Next.js.
Implementa la carga dinámica con la opción ssr: false:
import dynamic from 'next/dynamic'; const DynamicComponentWithNoSSR = dynamic( () => import('../components/MiComponente'), { ssr: false } ); export default function Page() { return (<DynamicComponentWithNoSSR />); }Método 3: Verificar y corregir el anidamiento HTML
A menudo, los navegadores corrigen automáticamente el HTML malformado antes de que React tome el control, lo que genera diferencias con el servidor. Revisa tu consola en busca de advertencias sobre elementos no válidos y asegúrate de cumplir con los estándares W3C en tu estructura JSX.