React
Explica renderizado en servidor, hidratación y streaming en React, incluyendo coincidencia inicial, límites de Suspense y errores comunes entre servidor y cliente.
Server-side rendering genera HTML en el servidor; hidratación conecta ese HTML con el árbol interactivo del cliente; streaming permite entregar el documento por partes. Son procesos relacionados, pero resuelven problemas diferentes y pueden ocurrir en momentos distintos.
En una aplicación renderizada únicamente en el cliente, el navegador suele recibir primero un documento HTML mínimo:
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>Después debe descargar JavaScript, ejecutarlo, obtener datos y construir la interfaz:
HTML mínimo
↓
descargar JavaScript
↓
ejecutar React
↓
cargar datos
↓
renderizar contenidoMientras ocurre ese trabajo, el usuario puede ver una pantalla vacía o un loading inicial.
Con server-side rendering, React ejecuta el árbol en el servidor y produce HTML que ya contiene una representación inicial de la pantalla:
request
↓
servidor ejecuta React
↓
HTML inicial
↓
navegador muestra contenido
↓
JavaScript se descarga e hidrataEsto puede mejorar:
SSR no garantiza por sí solo una aplicación rápida. Un servidor lento, JavaScript excesivo, datos en cascada o una hidratación costosa pueden eliminar parte del beneficio.
servidor
├─ ejecuta componentes
├─ obtiene un árbol React
└─ genera HTML
↓
red
↓
navegador
├─ analiza y muestra HTML
├─ descarga JavaScript
├─ ejecuta el primer render cliente
└─ hidrata el DOM existente
↓
aplicación interactivaEl HTML inicial es una fotografía. No contiene automáticamente el estado vivo de React, sus handlers ni todos los módulos necesarios para futuras interacciones.
Estos conceptos no son equivalentes.
El navegador genera la interfaz inicial mediante React:
import { createRoot } from "react-dom/client";
createRoot(document.getElementById("root")!).render(<App />);Usa createRoot cuando el contenedor no posee HTML generado previamente por React.
El servidor genera HTML para una petición y el cliente lo hidrata:
request → render servidor → HTML → hydrateRootNormalmente se calcula por solicitud, aunque una plataforma puede aplicar caché.
El HTML se genera antes de recibir la petición, por ejemplo durante un build o proceso de publicación:
build → HTML estático → CDN → navegadorPuede hidratarse igual que una página SSR si necesita interactividad.
Los Server Components producen una representación del árbol desde el servidor y permiten excluir su implementación del bundle cliente. No son simplemente “SSR mejorado”.
SSR → genera HTML inicial
RSC → divide componentes servidor/cliente y transporta una representaciónUn Client Component puede participar en SSR. Un Server Component no se hidrata como una instancia interactiva porque su implementación no viaja al navegador.
Las APIs de react-dom/server se ejecutan en el servidor, normalmente en el punto de entrada. Un framework suele invocarlas por ti.
Para entornos basados en Node.js, la API principal de streaming es:
import { renderToPipeableStream } from "react-dom/server";Ejemplo conceptual:
import express from "express";
import { renderToPipeableStream } from "react-dom/server";
import App from "./App";
const app = express();
app.get("*", (request, response) => {
let didError = false;
const { pipe, abort } = renderToPipeableStream(
<App url={request.url} />,
{
bootstrapScripts: ["/client.js"],
onShellReady() {
response.statusCode = didError ? 500 : 200;
response.setHeader("content-type", "text/html");
pipe(response);
},
onShellError(error) {
response.statusCode = 500;
response.send("<!doctype html><p>No fue posible cargar la página.</p>");
},
onError(error) {
didError = true;
console.error(error);
},
},
);
request.on("close", () => abort());
});Este ejemplo muestra el contrato general, no una infraestructura completa. En producción también debes gestionar headers, compresión, caché, bots, timeouts, seguridad, estáticos y logging.
En runtimes con Web Streams puedes utilizar:
import { renderToReadableStream } from "react-dom/server";
async function handleRequest() {
const stream = await renderToReadableStream(<App />, {
bootstrapScripts: ["/client.js"],
});
return new Response(stream, {
headers: {
"content-type": "text/html; charset=utf-8",
},
});
}React 19.2 también ofrece estas APIs por compatibilidad en Node.js, pero la documentación oficial recomienda las APIs específicas de Node Streams allí por rendimiento y compresión.
import { renderToString } from "react-dom/server";
const html = renderToString(<App />);renderToString genera un string completo, pero tiene soporte limitado de Suspense. Si un descendiente suspende, normalmente genera el fallback y no espera a que el contenido pendiente termine.
Para aplicaciones modernas con contenido progresivo, las APIs streaming suelen ser más apropiadas.
renderToStaticMarkup produce HTML no diseñado para hidratarse. Es útil para correos o documentos estáticos, no para una interfaz React interactiva.
En streaming, el shell es la parte del árbol que existe fuera de las boundaries de Suspense:
function ProductPage() {
return (
<html lang="es">
<body>
<Header />
<main>
<ProductSummary />
<Suspense fallback={<ReviewsSkeleton />}>
<ProductReviews />
</Suspense>
</main>
</body>
</html>
);
}En este caso, el shell incluye el documento, el encabezado, el resumen y el fallback de reseñas.
shell
├─ html
├─ Header
├─ ProductSummary
└─ ReviewsSkeletonCuando el shell está listo, el servidor puede empezar a responder sin esperar todo el árbol.
Una buena shell:
Streaming divide la respuesta en fragmentos:
1. shell y fallbacks
↓
2. contenido de una boundary
↓
3. contenido de otra boundary
↓
4. documento completadoEjemplo:
function Dashboard() {
return (
<main>
<h1>Panel principal</h1>
<Suspense fallback={<SummarySkeleton />}>
<Summary />
</Suspense>
<Suspense fallback={<OrdersSkeleton />}>
<RecentOrders />
</Suspense>
</main>
);
}Si Summary termina primero, el servidor puede enviar esa sección antes que RecentOrders.
El usuario obtiene progresivamente una pantalla más completa sin esperar que todo el servidor termine.
Suspense solo coordina fuentes compatibles. Entre ellas:
lazy.use.Este fetch no activa una boundary:
useEffect(() => {
fetch("/api/orders").then(/* ... */);
}, []);Los Effects no se ejecutan en el servidor y comienzan después de la hidratación en el cliente.
El navegador puede mostrar HTML recibido por streaming antes de descargar React:
HTML progresivo visible
≠
JavaScript listo
≠
hidratación completaUna sección puede estar visible pero todavía no responder a eventos. Esto se conoce como una brecha entre contenido visible e interactividad.
Por eso no debes asumir que “SSR significa interacción inmediata”.
La hidratación conecta un árbol React con DOM que ya existe:
import { hydrateRoot } from "react-dom/client";
import App from "./App";
hydrateRoot(document, <App />);Para un contenedor parcial:
hydrateRoot(
document.getElementById("root")!,
<App />,
);React no vuelve a crear todo el DOM desde cero. Intenta relacionar los elementos del primer render cliente con el HTML generado por el servidor y añade la capacidad interactiva necesaria.
Conceptualmente:
HTML existente
+
primer árbol cliente compatible
↓
React conecta handlers, state y refshydrateRoot espera que el cliente produzca el mismo contenido inicial que el servidor. Los mismatches deben tratarse como bugs.
function Clock() {
return <p>{new Date().toLocaleTimeString()}</p>;
}El servidor y el navegador pueden ejecutar en instantes, zonas horarias o locales distintos. El texto puede no coincidir.
Soluciones posibles:
type ClockProps = {
initialIsoDate: string;
};
function Clock({ initialIsoDate }: ClockProps) {
const [date, setDate] = useState(() => new Date(initialIsoDate));
useEffect(() => {
const id = window.setInterval(() => setDate(new Date()), 1000);
return () => window.clearInterval(id);
}, []);
return <time dateTime={date.toISOString()}>{formatTime(date)}</time>;
}El valor inicial debe ser idéntico en ambos entornos.
El servidor y el cliente cargan snapshots diferentes:
server: user = Ana
client: user = nullTransfiere o rehidrata el mismo estado inicial cuando corresponda.
const id = Math.random();
const createdAt = Date.now();No los produzcas durante ambos renders esperando igualdad.
function ThemeLabel() {
const isDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
return <p>{isDark ? "Oscuro" : "Claro"}</p>;
}window no existe en el servidor. Además, un check como este dentro del render tampoco garantiza HTML coincidente:
const isClient = typeof window !== "undefined";El servidor produciría una rama y el cliente otra.
const theme = localStorage.getItem("theme");Lee storage después del montaje o integra la preferencia mediante cookie/dato servidor cuando el HTML inicial debe respetarla.
El navegador puede corregir automáticamente una estructura inválida antes de que React hidrate:
<p><div>Contenido</div></p>El DOM resultante puede diferir del árbol esperado.
Whitespace añadido alrededor del root, extensiones del navegador o scripts que modifican el DOM pueden provocar diferencias.
Fechas, números y ordenaciones dependen del entorno. Usa una configuración explícita cuando necesites un resultado determinista.
useId genera identificadores compatibles con SSR e hidratación:
function EmailField() {
const id = useId();
return (
<div>
<label htmlFor={id}>Correo</label>
<input id={id} name="email" type="email" />
</div>
);
}Si hidratas múltiples raíces en la misma página, puedes utilizar identifierPrefix y debes usar el mismo prefijo en servidor y cliente.
No uses useId como key. Las keys provienen de la identidad de los datos.
Para una diferencia inevitable y localizada:
<time suppressHydrationWarning>
{new Date().toLocaleTimeString()}
</time>Es una salida de emergencia:
No lo coloques en un layout completo para apagar warnings.
Cuando realmente necesitas contenido distinto después de entrar al cliente:
function ClientOnlyInformation() {
const [isClient, setIsClient] = useState(false);
useEffect(() => {
setIsClient(true);
}, []);
return <p>{isClient ? "Contenido cliente" : "Contenido inicial estable"}</p>;
}El servidor y el primer render cliente muestran la misma rama. Después del Effect ocurre otro render.
Trade-offs:
Suspense permite que React coordine la hidratación por regiones en lugar de exigir que todo el documento termine como una unidad indivisible.
shell visible
├─ Header hidratado
├─ Search boundary pendiente
└─ Feed boundary hidratándoseReact puede priorizar trabajo relevante para la interacción y continuar con otras boundaries después. Esta capacidad no significa que debas diseñar cientos de boundaries pequeñas. La granularidad debe corresponder a unidades visuales e interactivas coherentes.
Los Effects no se ejecutan al generar HTML en el servidor:
useEffect(() => {
console.log("Solo después de montar en cliente");
}, []);Consecuencias:
useLayoutEffect tampoco mide layout en el servidor.Una biblioteca que usa layout puede necesitar una región cliente o un fallback estable.
El HTML puede presentar un botón antes de que su JavaScript esté listo:
<button onClick={handlePurchase}>Comprar</button>Diseña la experiencia considerando:
SSR mejora la aparición del contenido; reducir JavaScript mejora la llegada de la interacción.
Un error puede ocurrir antes o después de crear el shell.
Si falla contenido esencial fuera de Suspense, no existe una página mínima válida para transmitir. En Node, onShellError permite responder con un documento alternativo.
React puede transmitir el fallback de Suspense e intentar renderizar esa región nuevamente en cliente. Si también falla en cliente, una Error Boundary puede mostrar la recuperación correspondiente.
No muestres stack traces ni mensajes internos al usuario. Registra el error en servidor con un identificador de correlación.
Después de empezar a enviar bytes, normalmente ya no puedes cambiar el status code o headers.
Por eso debes decidir qué información pertenece al shell y qué errores pueden representarse dentro de la UI.
headers enviados
↓
stream iniciado
↓
status ya comprometidoUn framework suele coordinar redirects, not found, errores de ruta y boundaries antes de iniciar el stream.
Una petición puede cerrarse o superar un timeout. Debes abortar trabajo que ya no será entregado:
const { pipe, abort } = renderToPipeableStream(<App />, options);
setTimeout(() => {
abort();
}, 10_000);El framework puede implementar esta política. Abortar evita mantener trabajo inútil, pero debes decidir qué fallback o respuesta recibe el usuario.
Las APIs de servidor permiten declarar scripts de arranque:
renderToPipeableStream(<App />, {
bootstrapModules: ["/client.js"],
nonce: cspNonce,
});El nonce debe coincidir con la Content Security Policy de la respuesta. No construyas HTML concatenando valores no confiables.
Una store externa necesita un snapshot de servidor consistente:
const value = useSyncExternalStore(
subscribe,
getSnapshot,
getServerSnapshot,
);getServerSnapshot debe producir en el cliente inicial el mismo valor utilizado durante SSR. De lo contrario puede existir mismatch o un cambio inmediato.
Un fallback forma parte de la experiencia real:
<section aria-busy="true" aria-labelledby="orders-heading">
<h2 id="orders-heading">Pedidos recientes</h2>
<OrdersSkeleton />
</section>Considera:
role="alert".Los crawlers modernos pueden procesar contenido transmitido, pero el contenido esencial y los metadatos deben formar parte de una estrategia clara.
No coloques todo el contenido relevante detrás de una espera cliente iniciada en un Effect si necesitas que exista en el HTML inicial.
El framework puede manejar metadata, bots y streaming de forma específica; consulta su documentación.
SSR y streaming cambian dónde y cuándo ocurre el trabajo. No eliminan el coste.
Mide:
Un TTFB peor puede compensarse con HTML más útil, pero también puede retrasar todo. Evalúa la experiencia completa.
hydrateRoot acepta callbacks de errores:
hydrateRoot(document, <App />, {
onRecoverableError(error, errorInfo) {
reportHydrationError({ error, componentStack: errorInfo.componentStack });
},
onUncaughtError(error, errorInfo) {
reportClientError({ error, componentStack: errorInfo.componentStack });
},
});No reemplaces el logging por un callback que silencie errores. Registra release, ruta y contexto sin enviar información sensible.
React 19.2 incorpora APIs para pre-renderizar una parte estática y reanudar el trabajo dinámico después:
prerender
↓
prelude estático + estado pospuesto
↓
CDN o almacenamiento
↓
resume en una petición posterior
↓
stream SSR dinámicoEstas APIs son avanzadas y normalmente las integra un framework. No las presentes como requisito de una aplicación React común.
En Node.js, React recomienda las variantes específicas de Node Streams para este flujo.
En aplicaciones reales, un framework suele encargarse de:
Comprender React base permite diagnosticar problemas, pero la configuración concreta pertenece al framework. No conviertas una regla de Next.js, Remix u otro router en una regla universal de React.
Una SPA no es automáticamente una mala arquitectura. Elige según producto, datos, despliegue y experiencia.
suppressHydrationWarning.createRoot sobre HTML que debía hidratarse.hydrateRoot en una SPA sin HTML servidor.typeof window para producir dos árboles distintos.suppressHydrationWarning.renderToString como estrategia moderna completa de Suspense.createRoot inicia una raíz cliente; hydrateRoot reutiliza HTML React existente.suppressHydrationWarning es una salida limitada.Math.random() durante render puede romper hidratación?useEffect no activa Suspense en SSR?hydrateRoot en lugar de createRoot?suppressHydrationWarning?Server Components y límites cliente-servidor profundiza en qué código permanece en el servidor, qué cruza al bundle cliente y cómo se combinan RSC, SSR, Suspense y Actions.