dehydrate e hydrate en TanStack Query

Hay un momento revelador la primera vez que se conecta TanStack Query con renderizado en servidor: descubrir que la librería no inventa ningún concepto nuevo para el SSR. Todo lo que hace es aplicar con rigor las tres ideas que ya has visto por separado. Su cache es un estado que vive en memoria, así que en el servidor debe ser por petición o filtrará datos entre usuarios. Ese estado tiene que llegar al cliente, así que debe deshidratarse a una forma serializable y volver a inflarse al otro lado. Y el cliente, al recibirlo, no puede limitarse a mostrarlo: tiene que saber cuándo se obtuvo, para decidir si sigue siendo válido o si debe pedirlo otra vez. Lo elegante del diseño es que esas tres respuestas caben en cuatro piezas y que ninguna de ellas oculta lo que hace. El servidor precarga las consultas que la primera pantalla necesita, deshidrata la cache resultante a una estructura plana con sus claves, sus datos y sus marcas de tiempo, y el cliente la fusiona en su propia cache antes del primer render. El resultado, visto desde fuera, es una pantalla que aparece completa y ya no vuelve a parpadear: el navegador no pide lo que el servidor ya trajo, porque para él ese dato no es nuevo, es un dato que ya estaba en cache. Toda la lección consiste en entender por qué eso funciona y qué hay que vigilar para que siga funcionando.

El cliente de consultas es exactamente el singleton prohibido

Un cliente de consultas es una cache en memoria indexada por clave. Eso lo convierte, palabra por palabra, en el objeto que la lección anterior prohibía colocar en el ámbito de un módulo del servidor: guarda datos que dependen de quién pregunta, y compartirlo entre peticiones significa servir a un usuario la respuesta privada de otro. La regla, por tanto, es doble y asimétrica, y es la fuente de la mayoría de los errores de integración.

En el servidor, una instancia nueva por petición, siempre, sin excepción ni optimización. En el navegador, exactamente lo contrario: una única instancia estable que sobreviva a todos los renders, porque si se recrea en cada render la cache se vacía continuamente y la librería pierde su razón de ser. La forma habitual de conseguir ambas cosas con un solo módulo es una función que devuelva siempre una instancia nueva en el servidor y memorice una instancia perezosa en el navegador.

// Servidor: instancia nueva. Navegador: instancia unica y estable.
let clienteNavegador: QueryClient | undefined

export function obtenerCliente() {
  const crear = () =>
    new QueryClient({
      defaultOptions: { queries: { staleTime: 60_000 } },
    })

  if (typeof window === 'undefined') return crear() // por peticion
  return (clienteNavegador ??= crear())             // una sola vez
}

El umbral de frescura declarado por defecto no es un detalle cosmético en este contexto. Con el valor cero que trae la librería de fábrica, todo dato hidratado se considera obsoleto en el instante en que llega, y el cliente lo vuelve a pedir nada más montar: habrías pagado el coste de deshidratar para no ahorrar ni una petición. Un umbral positivo es lo que hace que el trabajo del servidor sirva de algo.

Merece la pena entender por qué la instancia del navegador debe memorizarse de forma perezosa y no crearse al importar el módulo. El módulo del cliente también se evalúa en el servidor durante el renderizado, porque es el mismo archivo; crear la instancia en el ámbito superior la construiría también allí, y volveríamos exactamente al singleton compartido entre peticiones. La comprobación diferida no es una micro-optimización sino la que mantiene separadas las dos reglas contrarias dentro de un único módulo isomorfo.

Precargar, deshidratar, fusionar

El flujo del servidor tiene tres pasos y ninguno es opcional. Se crea el cliente de la petición, se esperan las consultas que la primera pantalla necesita, y se deshidrata la cache resultante. El punto clave es la espera: si no se aguarda a que las consultas se resuelvan, la cache se deshidrata vacía y el HTML sale sin datos.

// SERVIDOR: precargar, esperar, deshidratar
const cliente = obtenerCliente()

await Promise.all([
  cliente.prefetchQuery({ queryKey: ['articulos'], queryFn: traerArticulos }),
  cliente.prefetchQuery({ queryKey: ['perfil', id], queryFn: () => traerPerfil(id) }),
])

const estado = dehydrate(cliente) // claves, datos y marcas de tiempo

Lo que dehydrate produce no es la cache sino su retrato: una estructura plana con la lista de consultas resueltas, cada una con su clave normalizada, sus datos y los metadatos temporales que permiten juzgar su frescura al llegar. No viaja ninguna función, ningún observador, ninguna suscripción; todo eso se reconstruye en el cliente. Esa estructura se serializa con las reglas de la primera lección y se incrusta en el documento.

En el cliente, la frontera de hidratación recibe ese retrato y lo inserta en la cache del cliente estable antes de que los componentes de su interior se rendericen por primera vez. La operación es una fusión, no un reemplazo: las consultas que ya existieran en la cache y sean más recientes se conservan, lo que importa cuando se navega entre páginas y cada una trae su propio bloque de datos deshidratados.

Que la fusión respete lo más reciente no es un detalle de implementación sino el requisito que hace segura la navegación del lado del cliente. Imagina que el usuario edita algo, la cache local queda con el valor nuevo, y a continuación navega a una página cuyo HTML deshidratado se generó antes de esa edición. Un reemplazo ciego devolvería la interfaz al pasado sin que nadie hubiera pedido nada; la fusión por marca temporal descarta lo viejo y conserva lo que el cliente ya sabía.

// CLIENTE: la frontera fusiona el estado antes del primer render
<QueryClientProvider client={obtenerCliente()}>
  <HydrationBoundary state={estadoDeshidratado}>
    <Pagina />
  </HydrationBoundary>
</QueryClientProvider>

flowchart TD
P[peticion entrante] --> C[cliente de consultas nuevo para esta peticion]
C --> F[prefetch de las consultas de la primera pantalla]
F --> D[dehydrate: claves, datos y marcas de tiempo]
D --> HT[serializado e incrustado en el HTML]
HT --> B[frontera de hidratacion en el navegador]
B --> M[fusion en la cache del cliente estable]
M --> V[los componentes leen de cache y no piden nada]
style V fill:#a6e3a1,color:#11111b

Qué merece viajar y qué debe quedarse

Deshidratar la cache entera es cómodo y casi siempre equivocado. Cada consulta añadida engorda el HTML, retrasa el primer pintado y expone su contenido a cualquiera que abra el código fuente. El criterio útil es la pregunta que ya conoces de la primera lección, aplicada consulta a consulta: sin este dato, la primera pantalla parpadea.

El desfase temporal y la revalidación al llegar

Todo dato deshidratado nace con una edad. El servidor lo obtuvo en un instante, el HTML tardó en generarse y viajar, el navegador tardó en descargar y ejecutar el JavaScript, y solo entonces se hidrata. Entre la consulta y el primer render del cliente ha pasado un tiempo que puede ir de decenas de milisegundos a minutos enteros si hay una cache de páginas por delante.

Por eso la marca temporal que acompaña a cada consulta deshidratada es la pieza que gobierna todo el comportamiento posterior. Al hidratar, el cliente no asume que el dato acaba de llegar: compara esa marca con el umbral de frescura configurado y decide. Si el dato aún está dentro del umbral, no pide nada y la pantalla queda quieta. Si ya lo ha superado, muestra de inmediato lo hidratado y lanza una revalidación en segundo plano, de modo que el usuario ve contenido al instante y la corrección llega después sin pantalla vacía.

Esa combinación es lo que hace que el patrón sea robusto ante el desfase: no promete que el dato sea actual, promete que será instantáneo y que se corregirá solo. La configuración del umbral es, por tanto, una declaración explícita de cuánta obsolescencia tolera cada dato, y merece pensarse por consulta y no de forma global.

// El umbral se declara por consulta segun lo que cada dato tolera
useQuery({ queryKey: ['articulo', id], queryFn: traer, staleTime: 300_000 })
useQuery({ queryKey: ['saldo'], queryFn: traer, staleTime: 0 })

Un artículo publicado tolera minutos de obsolescencia sin que nadie lo note; un saldo o un contador de existencias no tolera ninguno y debe revalidarse en cuanto el cliente pueda, aunque se hidrate. El umbral cero no invalida el deshidratado en ese segundo caso: el usuario sigue viendo el valor del servidor de inmediato, y la revalidación ocurre por detrás sin pantalla vacía. Lo que cambia es que se acepta pagar una petición extra a cambio de exactitud.