useSyncExternalStore no React: assine dados externos

useSyncExternalStore inscreve um componente em dados que vivem fora do React e o renderiza de novo sempre que esses dados mudam. Você passa duas funções: subscribe, que diz ao React como ouvir as mudanças, e getSnapshot, que retorna o valor atual.

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>
    );
}

Os dois componentes Display não compartilham props nem context, mas atualizam juntos, porque os dois assinam a mesma store. O botão chama uma função comum, não um setter do React. Adicione um terceiro <Display name="Sidebar" /> e ele entra no jogo sem nenhuma outra mudança.

A sintaxe

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

• subscribe(callback) começa a ouvir, chama callback sempre que os dados podem ter mudado e retorna uma função de cancelamento. O React a chama depois que o componente monta e chama a função retornada na desmontagem.
• getSnapshot() retorna o valor atual. O React a chama em toda renderização e depois de cada notificação e compara o resultado com o último usando Object.is. Mesmo valor, nenhuma renderização.
• getServerSnapshot() (opcional) retorna o valor a usar no servidor e durante a hidratação.

Defina subscribe fora do componente ou mantenha-a estável com useCallback. Se você passa uma função subscribe nova a cada renderização, o React cancela e assina de novo toda vez.

APIs do navegador como stores

Qualquer coisa que tenha um valor atual e dispare um evento quando ele muda se encaixa nesse formato. O navigator.onLine com os eventos online e offline é o caso clássico.

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>
    );
}

Desligue a sua rede (ou mude para Offline nas ferramentas de desenvolvedor do navegador) e o texto muda sem recarregar. O terceiro argumento diz "considere online" ao renderizar no servidor, onde não existe navigator. Envolver a chamada do hook em useOnlineStatus o torna um hook personalizado que qualquer componente pode usar.

A largura da janela funciona do mesmo jeito:

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>
    );
}

Adicione algumas cópias e redimensione a janela: todas as cópias mostram o mesmo número no mesmo momento. Cada cópia tem o próprio listener, e cada uma lê a largura durante a renderização, então nenhuma fica um frame atrás.

O getSnapshot precisa retornar um valor em cache

O React chama getSnapshot com frequência e compara os resultados por referência. Uma função que monta um objeto ou array novo a cada chamada sempre parece uma mudança:

// 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);
}

O React renderiza, chama getSnapshot, recebe um valor "diferente", renderiza de novo, e assim por diante, até parar com "Maximum update depth exceeded". Em desenvolvimento o React também registra antes "The result of getSnapshot should be cached to avoid an infinite loop". Um build de produção, como a prévia aqui, pula esse aviso e só reporta o erro final como um código curto (Minified React error #185).

A correção é manter os dados imutáveis na store: substitua o objeto quando ele mudar e retorne a referência guardada como está.

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>
    );
}

O getSnapshot retorna o mesmo objeto state até add substituí-lo, então o componente renderiza uma vez por mudança. A filtragem acontece no componente, depois de o snapshot ser lido, o que é seguro. Para filtrar dentro da store, calcule o array filtrado quando os dados mudarem e guarde-o, para que o getSnapshot possa retornar a cópia guardada.

getServerSnapshot e hidratação

No servidor não há janela, nem navigator, nem assinatura. O terceiro argumento diz ao React o que renderizar ali:

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

O React também usa o getServerSnapshot na primeira renderização no navegador, quando hidrata o HTML do servidor, para que os dois coincidam. Logo depois da hidratação ele lê o getSnapshot e, se o valor real for diferente, renderiza de novo com ele. Sem o terceiro argumento, a renderização no servidor lança "Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering." Se houver um <Suspense> acima do componente, o servidor envia o fallback desse boundary e o navegador renderiza o conteúdo; sem boundary, a renderização no servidor falha.

useSyncExternalStore vs useEffect e useState

Você pode assinar com um efeito:

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, com duas fraquezas. A primeira renderização sempre mostra o palpite inicial, e o valor real chega uma renderização depois, quando o efeito executa. E com renderização concorrente (durante uma transição, por exemplo), o React pode pausar uma renderização no meio; se a store mudar durante a pausa, componentes renderizados antes e depois podem mostrar valores diferentes. Essa inconsistência se chama tearing. O useSyncExternalStore lê o valor durante a renderização e faz o React refazer a renderização de forma síncrona se a store mudou, então todo componente vê o mesmo valor.

Use-o quando os dados vivem fora do React: o seu próprio módulo de store, uma API do navegador, uma biblioteca de terceiros. A maioria das bibliotecas de estado (Redux, Zustand e outras) o chama por você dentro dos próprios hooks. Para dados que pertencem aos seus componentes, useState, useReducer e context continuam sendo as ferramentas certas.