API e Parâmetros de useSyncExternalStore

useSyncExternalStore aceita até três argumentos: a função de inscrição, getSnapshot e um getServerSnapshot opcional. Juntos, eles informam ao React como ouvir mudanças e como ler o valor atual.

É essencial entender cada argumento, pois pequenos erros neles são a fonte mais comum de problemas ao usar este gancho.

A função de inscrição recebe uma função de retorno do React e deve registrá-la no armazenamento para que ela seja executada sempre que o armazenamento mudar. Ela deve retornar uma função para cancelar a inscrição, que o React chama durante a limpeza.

O React usa isso para saber quando deve reler o instantâneo; portanto, a inscrição trata exclusivamente de configurar e desmontar a notificação de mudanças.

getSnapshot retorna o valor atual do armazenamento. O React o chama durante a renderização para ler o estado e novamente após as notificações para detectar se o valor mudou.

É essencial que ele retorne um resultado estável por referência quando os dados subjacentes não tiverem mudado, retornando a mesma referência em vez de um objeto novo a cada chamada.

O getServerSnapshot opcional fornece o valor usado durante a renderização no servidor e a etapa inicial de hidratação. Ele existe porque o getSnapshot exclusivo do navegador pode depender de APIs que não existem no servidor.

Fornecê-lo evita incompatibilidades de hidratação ao dar ao servidor um valor adequado para renderizar, correspondente ao que o cliente produzirá inicialmente.

O gancho retorna o valor do instantâneo atual, que você usa diretamente no componente como qualquer outro elemento de estado. Quando o armazenamento muda, o React renderiza novamente e o gancho retorna o instantâneo atualizado.

Do ponto de vista do componente, isso parece a leitura de um estado reativo, embora a fonte de dados esteja inteiramente fora do React.

getSnapshot deve ser executado de forma síncrona e retornar um valor derivado exclusivamente do estado atual do armazenamento. Ele não deve realizar trabalho assíncrono nem produzir resultados diferentes para os mesmos dados subjacentes.

O React depende de chamá-lo repetidamente e comparar os resultados; portanto, qualquer não determinismo ou efeito colateral dentro dele pode causar um comportamento incorreto.

Armazenamentos que mantêm estado imutável tornam getSnapshot fácil de implementar, pois a referência do objeto de estado atual só muda quando os dados mudam. Retornar essa referência oferece comparações estáveis sem esforço adicional.

É por isso que os padrões de atualização imutável combinam tão bem com o gancho: dados iguais significam uma referência igual, e o React ignora novas renderizações desnecessárias.

Um erro frequente é retornar um objeto ou uma matriz totalmente novos a cada chamada de getSnapshot, por exemplo, ao mapear ou filtrar dados dentro dele. O React vê uma nova referência a cada vez e entende que o valor mudou.

Isso provoca novas renderizações infinitas ou avisos. A correção é armazenar em cache o valor derivado e retornar a mesma referência até que os dados de origem realmente mudem.

Para evitar o laço, calcule os dados derivados fora de getSnapshot ou memorize-os para que a função retorne uma referência armazenada em cache. O padrão baseado em seletores usado por muitas bibliotecas existe precisamente para gerenciar essa estabilidade.

A regra orientadora é que duas chamadas de getSnapshot com dados do armazenamento inalterados devem retornar exatamente a mesma referência.

Na prática, você escreve uma função de inscrição que adiciona e remove um ouvinte, um getSnapshot que lê um valor atual estável e, para SSR, um getServerSnapshot que retorna um valor seguro para o servidor.

Com esses três elementos corretos, o gancho oferece leituras consistentes e seguras em renderizações concorrentes do seu armazenamento externo, com o mínimo de configuração.

Identifique a função de getSnapshot.

O gancho recebe a função de inscrição, getSnapshot e, opcionalmente, getServerSnapshot. A função de inscrição configura um ouvinte e retorna uma função para cancelar a inscrição; getSnapshot lê o valor atual de forma síncrona e deve ser estável por referência; getServerSnapshot fornece um valor seguro para SSR.

O erro clássico é retornar um objeto novo a cada chamada, o que causa laços infinitos. Armazene os valores derivados em cache para que dados inalterados produzam a mesma referência.