React Academy · Lección

Errores de hidratación: causas y soluciones

Identifique discrepancias entre el HTML del servidor y del cliente y corríjalas con suppressHydrationWarning.

Errores de hidratación: causas y soluciones es una lección gratuita de React Academy en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de React Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de React Academy incluye 4 lecciones en total.

¿Qué es un error de hidratación?

Se produce un error de hidratación cuando el HTML renderizado por React en el servidor no coincide con el DOM virtual que React espera en el cliente. React registra una advertencia y vuelve a renderizar el componente desde cero, lo que provoca un parpadeo.

Causa común 1: valores aleatorios

Usar Math.random(), Date.now() o crypto.randomUUID() durante el renderizado produce valores diferentes en el servidor y en el cliente.

// Bad — different on server vs client:
<div id={Math.random().toString()}>...</div>

// Fix — use useId() (stable across server/client):
import { useId } from 'react';
function Component() {
  const id = useId();
  return <div id={id}>...</div>;
}

Causa común 2: API exclusivas del navegador

Leer localStorage, window.innerWidth o navigator durante el renderizado provoca un error en el servidor o produce valores diferentes.

// Bad — localStorage doesn't exist on server:
<div>{localStorage.getItem('theme')}</div>

// Fix — read in useEffect (client-only):
const [theme, setTheme] = useState('light');
useEffect(() => {
  setTheme(localStorage.getItem('theme') ?? 'light');
}, []);

Causa común 3: formato de fecha y hora

El formato de fecha según la configuración regional devuelve cadenas diferentes en el servidor (configuración regional UTC de Node) y en el cliente (configuración regional del navegador).

// Risky — locale may differ:
<time>{new Date().toLocaleDateString()}</time>

// Fix — use a consistent locale:
<time>{new Date().toLocaleDateString('en-US', { timeZone: 'UTC' })}</time>

Causa común 4: anidamiento de HTML no válido

React genera el HTML del cliente a partir del DOM virtual, pero un anidamiento de HTML no válido (por ejemplo, <p> dentro de <p>) hace que los navegadores reestructuren el DOM de forma diferente y provoca discrepancias.

// Bad — browser auto-closes the nested <p>:
<p>Outer <p>Inner</p> text</p>

// Fix — use <div> or correct semantic elements:
<div>Outer <p>Inner</p> text</div>

Causa común 5: renderizado condicional basado en el estado

Los componentes que se renderizan de forma diferente según un estado exclusivo del cliente (como la autenticación del usuario o el ancho de la pantalla) no coinciden porque el servidor renderiza sin ese estado.

// Bad — server renders 'Guest', client re-renders 'Alice' immediately:
<h1>{user?.name ?? 'Guest'}</h1>

// Fix — use a mounted guard to defer client-only rendering:
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return <h1>Guest</h1>; // match server output

suppressHydrationWarning

Utilice suppressHydrationWarning en los elementos donde las discrepancias sean intencionadas (por ejemplo, marcas de tiempo cuyo formato se aplica en el cliente). Suprime la advertencia únicamente para ese elemento.

<time suppressHydrationWarning dateTime={isoDate}>
  {new Date(isoDate).toLocaleString()}
</time>

Importación dinámica con ssr: false

En Next.js, utilice dynamic(fn, { ssr: false }) para impedir completamente que un componente se renderice en el servidor, eliminando así las discrepancias de hidratación de los componentes exclusivos del cliente.

import dynamic from 'next/dynamic';

const ClientOnlyChart = dynamic(() => import('./Chart'), { ssr: false });

export default function Dashboard() {
  return <ClientOnlyChart />; // only renders in the browser
}

Depuración de errores de hidratación

React 18 registra mensajes detallados sobre los errores de hidratación en el modo de desarrollo y muestra el nodo DOM exacto que no coincide. Utilice las DevTools del navegador para inspeccionar el HTML del servidor y el árbol de React.

useId para obtener identificadores estables

useId() genera identificadores únicos y estables que son coherentes entre los renderizados del servidor y del cliente; utilícelo para pares id/htmlFor y atributos ARIA.

function FormInput({ label }: { label: string }) {
  const id = useId();
  return (
    <div>
      <label htmlFor={id}>{label}</label>
      <input id={id} />
    </div>
  );
}

Pruebas de errores de hidratación

Ejecute su aplicación de Next.js en modo de desarrollo (npm run dev) y observe la consola del navegador. Las discrepancias de hidratación aparecen como advertencias en rojo con trazas de la pila de componentes.

Comprobación rápida

¿Cuál es la mejor solución para un componente que se renderiza de forma diferente en el servidor y el cliente porque lee datos de localStorage?

Repaso

Las discrepancias de hidratación se deben a valores aleatorios, API exclusivas del navegador, formatos sensibles a la configuración regional, anidamiento de HTML no válido y renderizado condicional exclusivo del cliente. Soluciónelas con useId(), useEffect para el estado exclusivo del cliente, suppressHydrationWarning para diferencias intencionadas y dynamic({ ssr: false }) para componentes exclusivos del cliente.

Preguntas frecuentes

¿La lección «Errores de hidratación: causas y soluciones» es gratis?

Sí — el texto completo de «Errores de hidratación: causas y soluciones» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de React Academy, actualiza a CoddyKit PRO. El curso de React Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Errores de hidratación: causas y soluciones»?

Identifique discrepancias entre el HTML del servidor y del cliente y corríjalas con suppressHydrationWarning. Practicas React Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar React Academy?

No se requiere experiencia previa. React Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «Errores de hidratación: causas y soluciones»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de React Academy?

Sí. Cada lección de React Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

Cómo funciona React SSR internamente
Errores de hidratación: causas y soluciones
Hidratación selectiva y HTML en streaming
Patrón de arquitectura de islas

← Volver a React Academy