API y parámetros de useSyncExternalStore

useSyncExternalStore recibe hasta tres argumentos: subscribe, getSnapshot y un getServerSnapshot opcional. Juntos indican a React cómo escuchar los cambios y cómo leer el valor actual.

Comprender cada argumento es esencial, ya que los pequeños errores en ellos son la fuente más común de problemas al usar este hook.

subscribe recibe un callback de React y debe registrarlo en el store para que se ejecute cada vez que el store cambie. Debe devolver una función para cancelar la suscripción, que React llamará durante la limpieza.

React utiliza esto para saber cuándo debe volver a leer la instantánea, por lo que subscribe se ocupa exclusivamente de conectar y desconectar las notificaciones de cambios.

getSnapshot devuelve el valor actual del store. React lo llama durante el renderizado para leer el estado y de nuevo después de las notificaciones para detectar si el valor cambió.

Es fundamental que devuelva un resultado estable por referencia cuando los datos subyacentes no hayan cambiado; debe devolver la misma referencia en lugar de crear un objeto nuevo cada vez.

El getServerSnapshot opcional proporciona el valor utilizado durante el renderizado en el servidor y la pasada inicial de hidratación. Existe porque el getSnapshot exclusivo del navegador puede depender de APIs que no están disponibles en el servidor.

Proporcionarlo evita desajustes de hidratación, ya que ofrece al servidor un valor razonable que coincide con lo que el cliente generará inicialmente.

El hook devuelve el valor de la instantánea actual, que usted utiliza directamente en su componente como cualquier otro fragmento de estado. Cuando el store cambia, React vuelve a renderizar y el hook devuelve la instantánea actualizada.

Desde la perspectiva del componente, se siente como leer estado reactivo, aunque la fuente de verdad viva completamente fuera de React.

getSnapshot debe ejecutarse de forma síncrona y devolver un valor derivado únicamente del estado actual del store. No debe realizar trabajo asíncrono ni producir resultados distintos para los mismos datos subyacentes.

React se basa en llamarlo repetidamente y comparar los resultados, por lo que cualquier comportamiento no determinista o efecto secundario en su interior puede provocar un funcionamiento incorrecto.

Los stores que contienen estado inmutable facilitan getSnapshot, ya que la referencia al objeto de estado actual solo cambia cuando cambian los datos. Devolver esa referencia proporciona comparaciones estables de forma automática.

Por eso los patrones de actualización inmutables combinan tan bien con el hook: si los datos son iguales, la referencia también lo es, y React omite los renderizados innecesarios.

Un error frecuente consiste en devolver un objeto o array completamente nuevo desde getSnapshot en cada llamada, por ejemplo, al aplicar un map o un filter en su interior. React ve una referencia nueva cada vez y cree que el valor cambió.

Esto provoca renderizados interminables o advertencias. La solución es almacenar en caché el valor derivado y devolver la misma referencia hasta que los datos de origen cambien realmente.

Para evitar el bucle, calcule los datos derivados fuera de getSnapshot o memorícelos para que la función devuelva una referencia almacenada en caché. El patrón basado en selectores que utilizan muchas bibliotecas existe precisamente para gestionar esta estabilidad.

La regla fundamental es que dos llamadas a getSnapshot con los datos del store sin cambios deben devolver exactamente la misma referencia.

En la práctica, escriba un subscribe que añada y elimine un listener, un getSnapshot que lea un valor actual estable y, para SSR, un getServerSnapshot que devuelva un valor seguro para el servidor.

Con los tres correctamente implementados, el hook ofrece lecturas coherentes y seguras en renderizado concurrente de su store externo, con muy poca complejidad adicional.

Identifique la función de getSnapshot.

El hook recibe subscribe, getSnapshot y, opcionalmente, getServerSnapshot. subscribe conecta un listener y devuelve una función para cancelar la suscripción; getSnapshot lee el valor actual de forma síncrona y debe ser estable por referencia; getServerSnapshot proporciona un valor seguro para SSR.

La trampa clásica consiste en devolver un objeto nuevo en cada llamada, lo que provoca bucles infinitos. Almacene en caché los valores derivados para que los datos sin cambios produzcan la misma referencia.