Lo que solo existe en el cliente

Hay una categoría de estado que ninguna de las técnicas anteriores puede rescatar, porque el problema no es de transporte sino de existencia. Puedes deshidratar lo que el servidor calculó y puedes aislar por petición lo que pertenece a cada usuario, pero no puedes enviar al cliente algo que el servidor nunca tuvo. El ancho de la ventana, la preferencia de tema del sistema operativo, el contenido de localStorage, la zona horaria del navegador, si el usuario está en línea, qué hay en el portapapeles: nada de eso existe en el proceso que genera el HTML, y no por una limitación técnica que alguna versión futura vaya a resolver, sino porque son propiedades del dispositivo que hace la petición y el servidor solo recibe de él lo que quepa en una cabecera HTTP. El reflejo inmediato ante ese vacío es preguntar si estamos en el navegador y ramificar, y ese reflejo es precisamente lo que hay que desaprender, porque produce un componente que devuelve una cosa en el servidor y otra en el cliente, que es la definición exacta de lo que rompe la adopción del árbol. La disciplina correcta invierte el orden: primero se decide qué renderiza el servidor, ese valor se renderiza también en el cliente en el fotograma cero, y solo después se corrige. Toda la sofisticación está en elegir bien el valor neutro y en decidir cuánto tiempo puede vivir la interfaz mostrándolo.

El entorno amputado y el único canal abierto

El proceso que renderiza en el servidor es un entorno de JavaScript sin interfaz de usuario. No es que las APIs del navegador estén vacías: es que no existen, porque pertenecen a una plataforma distinta. Lo único que el servidor sabe del cliente es lo que este le contó al pedir la página, y eso cabe en una lista corta: la URL con sus parámetros, las cabeceras estándar —idiomas aceptados, agente de usuario, sugerencias del cliente si están habilitadas— y las cookies.

De ahí se deduce un criterio operativo muy limpio. Todo dato del dispositivo pertenece a una de dos clases: los que pueden llegar por ese canal y los que no. El idioma preferido llega por cabecera. Una preferencia guardada puede llegar si la escribes en una cookie en lugar de en localStorage. El ancho exacto de la ventana no llega nunca. La preferencia de tema del sistema tampoco, salvo que el navegador envíe la sugerencia correspondiente y tú la negocies explícitamente.

La consecuencia práctica es que la primera decisión de diseño no es cómo detecto esto en el cliente, sino puedo mover esta información al canal que el servidor sí escucha. Cada dato que consigues trasladar deja de ser un problema de hidratación y pasa a ser un dato normal, disponible desde el primer byte.

Ese traslado tiene un precio que conviene conocer antes de abusar de él. Una cookie viaja en cada petición al mismo origen, incluidas las de recursos estáticos si no restringes su ámbito, así que engorda todas las subidas y no solo la del documento. Además, cualquier respuesta que dependa de una cookie deja de ser cacheable de forma compartida salvo que declares explícitamente esa variación. Mover un dato al canal del servidor convierte un problema de hidratación en un problema de cache, y la segunda conversación suele ser más barata, pero hay que tenerla.

// El servidor lee lo que la peticion le cuenta, nada mas
const idioma = peticion.headers.get('accept-language')?.split(',')[0]
const tema = leerCookie(peticion, 'tema') ?? 'claro'
const ancho = null // no existe: ninguna cabecera lo transporta

La regla del valor neutro

La disciplina cabe en una frase: el primer render del cliente debe ser idéntico al del servidor, así que empieza por elegir qué renderiza el servidor cuando no sabe. Ese valor por defecto no es un relleno arbitrario; es una decisión de producto que conviene tomar a conciencia, porque muchos usuarios lo verán durante unos milisegundos y algunos lo verán durante bastante más si su conexión es lenta.

Hay un cuarto criterio que solo aparece cuando el equipo lleva tiempo con SSR: el valor neutro debe ser explicable. Alguien recibirá un informe de que la página se ve rara durante un instante, y la respuesta debe poder ser esto es el valor por defecto que servimos mientras no conocemos el dispositivo, no vaya usted a saber. Escribirlo como constante con nombre, en lugar de como número suelto dentro de un componente, convierte una rareza inexplicable en una decisión documentada.

Un buen valor neutro cumple tres condiciones. Es válido por sí mismo, en el sentido de que la interfaz no parece rota mientras se muestra. Es el más probable, para que la corrección posterior afecte a la minoría. Y ocupa el mismo espacio que el valor real, para que el ajuste no desplace el contenido y provoque un salto visual.

// Valor neutro en el primer render, correccion suscrita despues
const anchoNeutro = 1024

const ancho = useSyncExternalStore(
  suscribirAResize,            // alta y baja del listener
  () => window.innerWidth,     // instantanea real en el cliente
  () => anchoNeutro,           // instantanea en el servidor
)

Declarar la instantánea de servidor de forma explícita, como en el ejemplo, es preferible a una bandera de montado porque hace visible en el propio código cuál es el valor neutro elegido, en lugar de esconderlo en el estado inicial de un componente. El resultado observable es el mismo; la diferencia está en que el contrato queda escrito.

La tercera condición, la del espacio ocupado, es la que más se descuida y la que más daña la experiencia percibida. Si el valor neutro produce un bloque de altura distinta a la del valor real, la corrección empuja todo lo que hay debajo y el usuario ve saltar la página justo cuando iba a leer o a pulsar. Reservar el hueco desde el primer render —con una altura mínima, una proporción fija o un esqueleto del mismo tamaño— convierte un salto visible en un cambio de contenido que casi nadie percibe.

flowchart TD
S[servidor renderiza el valor neutro] --> H[HTML entregado y adoptado sin divergencia]
H --> M[componente montado en el cliente]
M --> L[lectura de la fuente real del navegador]
L --> Q{coincide con el valor neutro}
Q -->|si| Q1[nada cambia y el usuario no percibe nada]
Q -->|no| Q2[actualizacion en el segundo fotograma]
style Q1 fill:#a6e3a1,color:#11111b
style Q2 fill:#f9e2af,color:#11111b

Cuatro maneras de ajustar, ordenadas por lo que conceden

Merece subrayarse la segunda, porque es la que más se olvida y la única que elimina el problema en lugar de gestionarlo. Muchísimo estado de cliente existe únicamente porque alguien decidió resolver con JavaScript algo que el motor de estilos ya sabe hacer sin ayuda. Un valor de punto de ruptura leído del ancho de la ventana casi siempre puede sustituirse por una consulta de medios o de contenedor; el tema que sigue al sistema operativo puede resolverse con una consulta de esquema de color. Donde no hay variable no hay hidratación que romper, ni valor neutro que elegir, ni ajuste que temporizar.

La cuarta opción merece una advertencia porque su coste se paga en un lugar donde nadie mira. Sacar una isla del servidor no solo elimina su HTML inicial: retrasa su aparición hasta que el JavaScript se descarga, se analiza y se ejecuta, lo que en una conexión mediocre son segundos, no milisegundos. Si esa isla ocupa la parte visible de la pantalla, el usuario mira un hueco durante todo ese tiempo, y las métricas de estabilidad visual y de mayor elemento pintado lo registran. Es una herramienta legítima para un widget que de todos modos no aporta al primer fotograma, y una mala decisión para casi todo lo demás.

El tema oscuro, resuelto de punta a punta

El tema es el caso de estudio perfecto porque combina las tres fuentes posibles y porque el fallo es visible a simple vista: el destello blanco antes de que el tema oscuro se aplique. La preferencia puede venir del sistema operativo, mediante una consulta de medios; de una elección explícita del usuario, guardada en algún sitio; o del valor por defecto de la aplicación cuando no hay ninguna de las dos.

La solución canónica no es un componente sino un fragmento síncrono ejecutado en el encabezado del documento, antes de que el navegador pinte el primer píxel. Lee la preferencia guardada, cae en la consulta de medios si no hay ninguna, y escribe el resultado como atributo en el elemento raíz.

// En el head, antes de cualquier render del framework
const guardado = localStorage.getItem('tema')
const sistema = matchMedia('(prefers-color-scheme: dark)').matches
document.documentElement.dataset.tema = guardado ?? (sistema ? 'oscuro' : 'claro')

Conviene entender por qué esto no provoca divergencia, porque parece contradecir todo lo dicho. La clave es que el fragmento no participa en el árbol que el framework va a adoptar: escribe un atributo en el elemento raíz del documento, que está fuera del subárbol hidratado, y lo hace antes de que el framework siquiera arranque. Cuando llega la hidratación, el árbol servido y el calculado siguen coincidiendo, porque ninguno de los dos menciona el tema; el tema vive en CSS, gobernado por ese atributo. Se paga un script bloqueante de microsegundos y se compra la ausencia total de destello.

Si además el usuario puede cambiar el tema desde la interfaz, esa elección se escribe en el atributo y, si quieres que el servidor la conozca en futuras visitas, también en una cookie. A partir de ahí el servidor pinta el atributo correcto desde el primer byte y el fragmento del encabezado queda como red de seguridad para la primera visita, cuando aún no había cookie.

El resultado final tiene una propiedad que conviene reconocer porque es el objetivo de todo el nivel: no hay ningún estado de tema en el árbol hidratado. El tema es un atributo del documento leído por reglas de estilo, la elección del usuario es una escritura en dos sitios y el componente que la ofrece no tiene que renderizar nada distinto en servidor y en cliente. Eliminar el estado, cuando se puede, es siempre mejor que sincronizarlo bien.