Busca Básica de Dados com SWR

Receita

Use o hook useSWR com uma chave e uma função fetcher para buscar, cachear e revalidar dados remotos declarativamente em componentes React.

"use client";
 
import useSWR from "swr";
 
const fetcher = (url: string) => fetch(url).then((res) => res.json());
 
function Dashboard() {
  const { data, error, isLoading, isValidating } = useSWR("/api/dashboard", fetcher);
 
  if (isLoading) return <p>Carregando...</p>;
  if (error) return <p>Erro: {error.message}</p>;
 
  return (
    <div>
      <h1>{data.title}</h1>
      {isValidating && <span>Atualizando...</span>}
    </div>
  );
}

Exemplo Funcional

"use client";
 
import useSWR from "swr";
 
interface User {
  id: number;
  name: string;
  email: string;
}
 
const fetcher = (url: string): Promise<User[]> =>
  fetch(url).then((res) => {
    if (!res.ok) throw new Error("A resposta da rede não foi ok");
    return res.json();
  });
 
export default function UserList() {
  const { data: users, error, isLoading } = useSWR<User[]>("/api/users", fetcher);
 
  if (isLoading) return <div className="skeleton" />;
  if (error) return <div role="alert">Falha ao carregar usuários</div>;
 
  return (
    <ul>
      {users?.map((user) => (
        <li key={user.id}>
          {user.name} - {user.email}
        </li>
      ))}
    </ul>
  );
}

Análise Detalhada

Como Funciona

• O primeiro argumento para useSWR é a chave - uma string única (ou array, ou null) que identifica a requisição e controla o cache.
• O segundo argumento é o fetcher - qualquer função assíncrona que recebe a chave e retorna dados.
• SWR retorna dados cacheados imediatamente (stale), depois revalida em segundo plano (while revalidate) e, finalmente, atualiza a UI com dados frescos.
• isLoading é true apenas na primeira carga, quando ainda não há dados cacheados.
• isValidating é true sempre que uma requisição está em andamento, incluindo revalidações em segundo plano.
• SWR deduplica requisições idênticas feitas dentro da janela dedupingInterval (padrão: 2000ms).

Variações

Chaves de array (fetcher com múltiplos argumentos):

const fetcher = ([url, token]: [string, string]) =>
  fetch(url, { headers: { Authorization: `Bearer ${token}` } }).then((r) => r.json());
 
const { data } = useSWR(["/api/user", token], fetcher);

Usando axios:

import axios from "axios";
 
const fetcher = (url: string) => axios.get(url).then((res) => res.data);
 
const { data } = useSWR("/api/posts", fetcher);

Fetcher GraphQL:

const fetcher = (query: string) =>
  fetch("/api/graphql", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query }),
  })
    .then((res) => res.json())
    .then((json) => json.data);
 
const { data } = useSWR("{ user { name } }", fetcher);

Notas de TypeScript

• Passe genéricos para useSWR para tipar o retorno: useSWR<Data, Error>(key, fetcher).
• O tipo de retorno da função fetcher deve corresponder ao genérico Data.
• O tipo da chave pode ser string, [string, ...args], ou uma função que retorne um dos dois.

import useSWR, { Fetcher } from "swr";
 
const fetcher: Fetcher<User[], string> = (url) =>
  fetch(url).then((r) => r.json());
 
const { data } = useSWR<User[]>("/api/users", fetcher);
// data é User[] | undefined

Armadilhas

• A chave deve ser uma referência estável. Criar um novo literal de array inline a cada renderização (por exemplo, useSWR([url, id], ...)) é aceitável porque SWR serializa chaves de array internamente, mas chaves de objeto não são suportadas.
• Se o seu fetcher não lançar erro em requisições HTTP, SWR tratará uma resposta 404 ou 500 como dados bem-sucedidos. Sempre verifique res.ok no seu fetcher.
• data é undefined durante a carga inicial. Sempre trate o estado de carregamento ou use encadeamento opcional.
• Chamar useSWR em um Server Component resultará em erro. Hooks SWR são apenas para o lado do cliente.

Alternativas

Exemplo do Mundo Real

De uma aplicação SaaS de produção Next.js 15 / React 19 (SystemsArchitect.io).

// Exemplo de produção: Busca com SWR + debouncing
// Arquivo: src/hooks/use-search.ts
export function useSearch() {
  const [debouncedQuery, setDebouncedQuery] = useState(query);
 
  useEffect(() => {
    const timer = setTimeout(() => setDebouncedQuery(query), 300);
    return () => clearTimeout(timer);
  }, [query]);
 
  const shouldFetch = debouncedQuery.length >= 3;
  const apiUrl = shouldFetch
    ? `/api/search?q=${encodeURIComponent(debouncedQuery)}&platform=${platform}`
    : null;
 
  const { data, error, isLoading, isValidating } = useSWR<SearchResponse>(
    apiUrl,
    fetcher,
    {
      revalidateOnFocus: false,
      revalidateOnReconnect: false,
      dedupingInterval: 5000,
      keepPreviousData: true,
    }
  );
 
  return useMemo(() => ({
    results: data?.results,
    isLoading: isLoading || (shouldFetch && isValidating),
  }), [data, isLoading, shouldFetch, isValidating]);
}

O que isso demonstra em produção:

• Passar null como chave SWR impede completamente a busca. Esta é a maneira idiomática de buscar condicionalmente: quando shouldFetch é falso, a URL é null e SWR pula a requisição.
• keepPreviousData: true preserva os resultados de busca anteriores enquanto uma nova consulta está em andamento, evitando um flash de tela em branco entre as transições de chave.
• dedupingInterval: 5000 impede requisições duplicadas para a mesma chave dentro de 5 segundos. Se o usuário digitar "react", deletar e digitar "react" novamente em 5 segundos, SWR retornará o resultado cacheado em vez de acionar a API.
• revalidateOnFocus: false e revalidateOnReconnect: false desativam a revalidação automática em segundo plano. Para buscas, resultados stale são aceitáveis e revalidar ao focar na aba seria surpreendente para os usuários.
• O useMemo no objeto de retorno impede que os componentes consumidores re-renderizem quando o estado interno do hook muda, mas os valores retornados não mudaram.
• O estado de carregamento combina isLoading (primeira carga) com isValidating (busca em segundo plano) para um indicador de carregamento completo.

FAQs

const fetcher = ([url, token]: [string, string]) =>
  fetch(url, {
    headers: { Authorization: `Bearer ${token}` },
  }).then((r) => r.json());
 
const { data } = useSWR(["/api/user", token], fetcher);

import useSWR, { Fetcher } from "swr";
 
const fetcher: Fetcher<User[], string> = (url) =>
  fetch(url).then((r) => r.json());
 
const { data } = useSWR<User[]>("/api/users", fetcher);
// data é User[] | undefined

Links Relacionados

• SWR Data Fetching
• SWR Key Arguments
• SWR API