Hook useSWR: busca, carregamento e estados de erro

useSWR(key, fetcher, options) é o hook principal. key é a chave do cache (geralmente uma cadeia de caracteres de URL), fetcher é a função assíncrona que retorna os dados, e options é um objeto de configuração opcional.

O hook retorna um objeto com data, error, isLoading, isValidating e a função mutate.

A chave pode ser uma URL em formato de cadeia de caracteres, uma lista de [url, params] ou null. Chaves em formato de cadeia de caracteres correspondem a solicitações GET simples. Chaves em formato de lista permitem incorporar variáveis, como userId ou filters, à identidade do cache.

Passar null desativa completamente a solicitação, o que é útil para buscas condicionais quando os dados necessários ainda não estão disponíveis.

A função de busca recebe a chave (ou a chave de lista expandida como argumentos) e deve retornar uma Promise. O valor resolvido torna-se data. Se a função de busca lançar uma exceção, a propriedade error será definida.

Exemplo: (url) => fetch(url).then(r => { if (!r.ok) throw new Error(r.status); return r.json(); }).

data é undefined durante o primeiro carregamento e passa a ser igual ao valor resolvido pela função de busca após o sucesso. error é undefined a menos que a função de busca lance uma exceção; nesse caso, contém o objeto de erro lançado.

Verifique if (error) para renderizar uma mensagem de erro e if (!data) para renderizar um esqueleto de carregamento, fornecendo interfaces substitutas claras.

isLoading só é true quando não há dados em cache e uma solicitação está em andamento: o primeiro carregamento dessa chave. isValidating é true sempre que uma solicitação está em andamento, incluindo revalidações em segundo plano quando já existem dados em cache.

Use isLoading para telas de esqueleto; use isValidating para um indicador discreto que sinalize uma atualização em segundo plano.

SWRConfig permite definir a função de busca padrão, dedupingInterval, refreshInterval, o manipulador onError e outras opções para todas as chamadas de useSWR dentro da subárvore. Isso centraliza a configuração, em vez de repetir opções em cada hook.

Aninhe vários provedores SWRConfig para ter padrões diferentes em diferentes seções da aplicação.

Passe null como chave para ignorar a solicitação: useSWR(isLoggedIn ? '/api/user' : null, fetcher). SWR não fará a busca até que a chave se torne um valor diferente de null.

Isso é mais simples do que a opção de ignorar do React Query. A transição da chave de null para uma cadeia de caracteres aciona automaticamente a primeira busca.

Encadeie hooks do SWR para solicitações dependentes: const { data: user } = useSWR('/api/me', fetcher) e depois const { data: orders } = useSWR(user ? '/api/orders/' + user.id : null, fetcher). O segundo hook espera até que o primeiro seja resolvido.

Esse padrão evita cadeias de useEffect e mantém as dependências de dados declarativas e fáceis de ler.

Se um componente Header e um componente Sidebar chamarem useSWR('/api/user', fetcher), SWR fará apenas uma solicitação e compartilhará o resultado. Os dois componentes serão renderizados novamente juntos quando os dados ou o erro forem atualizados.

Essa deduplicação acontece automaticamente dentro da janela de dedupingInterval (o padrão é 2000 ms), sem nenhuma configuração adicional.

refreshInterval: 5000 faz consultas a cada 5 segundos. refreshWhenHidden: false interrompe as consultas quando a aba não está visível. shouldRetryOnError: false desativa a nova tentativa automática. revalidateOnFocus: false desativa a revalidação acionada pelo foco.

Combine as opções para atender aos requisitos de atualização dos seus dados: painéis costumam usar refreshInterval, enquanto conteúdos estáticos definem revalidateOnFocus: false.

Para dados paginados, inclua o número da página na chave: useSWR(['/api/items', page], fetcher). Mudar de página aciona uma nova busca para essa página, mantendo as páginas anteriores em cache.

SWR também fornece useSWRInfinite para padrões baseados em cursor ou de rolagem infinita, com uma função getKey que cria chaves com base no índice da página e nos dados da página anterior.

O que acontece quando você passa null como chave para useSWR?

useSWR(key, fetcher) retorna data, error, isLoading e isValidating. Chaves null desativam a busca em solicitações condicionais e dependentes. isLoading indica o primeiro carregamento; isValidating indica qualquer solicitação em andamento. SWRConfig centraliza os padrões, e a deduplicação de solicitações entre componentes é automática.

Opções como refreshInterval, revalidateOnFocus e shouldRetryOnError ajustam detalhadamente o comportamento de atualização dos dados por hook ou globalmente.