useSyncExternalStore en React: suscribirse a datos externos

useSyncExternalStore suscribe un componente a datos que viven fuera de React y lo vuelve a renderizar cada vez que esos datos cambian. Le das dos funciones: subscribe, que le dice a React cómo escuchar los cambios, y getSnapshot, que devuelve el valor actual.

import { useSyncExternalStore } from 'react';

// A tiny store that lives outside React
let count = 0;
const listeners = new Set();

const counterStore = {
    increment() {
        count += 1;
        listeners.forEach((listener) => listener());
    },
    subscribe(listener) {
        listeners.add(listener);
        return () => listeners.delete(listener);
    },
    getSnapshot() {
        return count;
    },
};

function Display({ name }) {
    const value = useSyncExternalStore(counterStore.subscribe, counterStore.getSnapshot);
    console.log(name, 'rendered with', value);
    return <p>{name} sees {value}</p>;
}

export default function App() {
    return (
        <div>
            <Display name="Header" />
            <Display name="Footer" />
            <button onClick={counterStore.increment}>Increment the store</button>
        </div>
    );
}

Los dos componentes Display no comparten props ni contexto, y aun así se actualizan juntos, porque ambos se suscriben al mismo store. El botón llama a una función normal, no a un setter de React. Agrega un tercer <Display name="Sidebar" /> y se suma sin ningún otro cambio.

La sintaxis

const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?);

• subscribe(callback) empieza a escuchar, llama a callback cada vez que los datos pueden haber cambiado y devuelve una función para cancelar la suscripción. React la llama después de que el componente se monta y llama a la función devuelta al desmontar.
• getSnapshot() devuelve el valor actual. React la llama durante cada renderizado y después de cada aviso, y luego compara el resultado con el último usando Object.is. Mismo valor, ningún renderizado.
• getServerSnapshot() (opcional) devuelve el valor que se usa en el servidor y durante la hidratación.

Define subscribe fuera del componente, o mantenlo estable con useCallback. Si pasas una función subscribe nueva en cada renderizado, React cancela la suscripción y vuelve a suscribirse cada vez.

APIs del navegador como stores

Cualquier cosa que tenga un valor actual y dispare un evento cuando el valor cambia encaja en esta forma. navigator.onLine con los eventos online y offline es el caso clásico.

import { useSyncExternalStore } from 'react';

function subscribe(callback) {
    window.addEventListener('online', callback);
    window.addEventListener('offline', callback);
    console.log('subscribed to online/offline');
    return () => {
        window.removeEventListener('online', callback);
        window.removeEventListener('offline', callback);
    };
}

function useOnlineStatus() {
    return useSyncExternalStore(
        subscribe,
        () => navigator.onLine,
        () => true
    );
}

export default function App() {
    const online = useOnlineStatus();
    return (
        <p style={{ color: online ? '#1a7f37' : '#c0392b' }}>
            {online ? 'You are online' : 'You are offline: changes will sync later'}
        </p>
    );
}

Desactiva tu red (o cambia a Offline en las herramientas de desarrollo de tu navegador) y el texto cambia sin recargar. El tercer argumento dice "supón que hay conexión" al renderizar en el servidor, donde no existe navigator. Envolver la llamada al hook en useOnlineStatus lo convierte en un hook personalizado que cualquier componente puede usar.

El ancho de la ventana funciona igual:

import { useSyncExternalStore, useState } from 'react';

function subscribe(callback) {
    window.addEventListener('resize', callback);
    return () => window.removeEventListener('resize', callback);
}

function useWindowWidth() {
    return useSyncExternalStore(subscribe, () => window.innerWidth, () => 1024);
}

function Layout() {
    const width = useWindowWidth();
    return <p>{width}px: {width < 600 ? 'one column' : 'two columns'}</p>;
}

export default function App() {
    const [copies, setCopies] = useState(1);
    return (
        <div>
            <button onClick={() => setCopies(copies + 1)}>Add a copy</button>
            {Array.from({ length: copies }, (_, i) => (
                <Layout key={i} />
            ))}
        </div>
    );
}

Agrega algunas copias y cambia el tamaño de la ventana: cada copia muestra el mismo número en el mismo momento. Cada copia tiene su propio listener, y cada una lee el ancho durante el renderizado, así que ninguna va nunca un frame atrasada.

getSnapshot debe devolver un valor en caché

React llama a getSnapshot a menudo y compara los resultados por referencia. Una función que construye un objeto o array nuevo en cada llamada siempre parece un cambio:

// Broken: a new object on every call
function getSnapshot() {
    return { count: store.count, user: store.user };
}

// Also broken: filter returns a new array every time
function getSnapshot() {
    return store.todos.filter((t) => !t.done);
}

React renderiza, llama a getSnapshot, recibe un valor "distinto", vuelve a renderizar, y así sucesivamente, hasta que se detiene con "Maximum update depth exceeded". En desarrollo React además registra antes "The result of getSnapshot should be cached to avoid an infinite loop". Un build de producción, como la vista previa de aquí, omite esa advertencia y reporta solo el error final como un código corto (Minified React error #185).

La solución es mantener los datos inmutables en el store: reemplaza el objeto cuando cambie y devuelve la referencia guardada tal cual.

import { useSyncExternalStore } from 'react';

let state = { todos: [{ id: 1, text: 'Write docs', done: false }] };
const listeners = new Set();

const todoStore = {
    add(text) {
        state = { ...state, todos: [...state.todos, { id: Date.now(), text, done: false }] };
        listeners.forEach((l) => l());
    },
    subscribe(listener) {
        listeners.add(listener);
        return () => listeners.delete(listener);
    },
    getSnapshot() {
        return state;
    },
};

export default function App() {
    const { todos } = useSyncExternalStore(todoStore.subscribe, todoStore.getSnapshot);
    const open = todos.filter((t) => !t.done);
    console.log('render,', todos.length, 'todos');
    return (
        <div>
            <button onClick={() => todoStore.add('Another task')}>Add task</button>
            <ul>
                {open.map((t) => (
                    <li key={t.id}>{t.text}</li>
                ))}
            </ul>
        </div>
    );
}

getSnapshot devuelve el mismo objeto state hasta que add lo reemplaza, así que el componente renderiza una vez por cambio. El filtrado ocurre en el componente, después de leer el snapshot, y eso es seguro. Para filtrar dentro del store, calcula el array filtrado cuando cambian los datos y guárdalo, para que getSnapshot pueda devolver la copia guardada.

getServerSnapshot e hidratación

En el servidor no hay ventana, ni navigator, ni suscripción. El tercer argumento le dice a React qué renderizar ahí:

const width = useSyncExternalStore(
    subscribe,
    () => window.innerWidth, // in the browser
    () => 1024 // on the server, and during hydration
);

React también usa getServerSnapshot para el primer renderizado en el navegador cuando hidrata el HTML del servidor, para que ambos coincidan. Justo después de la hidratación lee getSnapshot y, si el valor real es distinto, vuelve a renderizar con él. Sin el tercer argumento, el renderizado en el servidor lanza "Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering." Si hay un límite <Suspense> por encima del componente, el servidor envía el fallback de ese límite y el navegador renderiza su contenido; sin ningún límite, el renderizado en el servidor falla.

useSyncExternalStore vs useEffect y useState

Puedes suscribirte con un efecto:

function useOnlineStatus() {
    const [online, setOnline] = useState(true);
    useEffect(() => {
        const update = () => setOnline(navigator.onLine);
        update();
        window.addEventListener('online', update);
        window.addEventListener('offline', update);
        return () => {
            window.removeEventListener('online', update);
            window.removeEventListener('offline', update);
        };
    }, []);
    return online;
}

Funciona, con dos debilidades. El primer renderizado siempre muestra la suposición inicial, y el valor real llega un renderizado después, cuando se ejecuta el efecto. Y con el renderizado concurrente (durante una transición, por ejemplo), React puede pausar un renderizado a mitad de camino; si el store cambia durante la pausa, los componentes renderizados antes y después pueden mostrar valores distintos. Esa inconsistencia se llama tearing. useSyncExternalStore lee el valor durante el renderizado y hace que React rehaga el renderizado de forma síncrona si el store cambió, así que todos los componentes ven el mismo valor.

Úsalo cuando los datos vivan fuera de React: tu propio módulo de store, una API del navegador, una librería de terceros. La mayoría de las librerías de estado (Redux, Zustand y otras) lo llaman por ti dentro de sus hooks. Para los datos que pertenecen a tus componentes, useState, useReducer y el contexto siguen siendo las herramientas adecuadas.