React Data Hook
Um guia para buscar dados do servidor em React da maneira correta: tipado, cancelável e com estados de carregamento + erro sempre tratados.
Princípios
- Um componente deve renderizar estado, não orquestrar requisições. Coloque a busca em um hook para que o componente permaneça declarativo.
- Sempre modele três estados —
loading,error,data. Nunca presuma que a requisição foi bem-sucedida. - Cancele requisições em andamento quando o componente desmontar ou as entradas mudarem. Uma resposta tardia que atualiza uma UI desmontada ou desatualizada é um bug real (flicker, dados errados, avisos do React), não teórico.
- Tipifique a resposta. Um hook que retorna
anyapenas move o bug para downstream.
Primeiro: prefira uma biblioteca de dados real quando houver uma
Se o projeto já usa TanStack Query (React Query) ou SWR, use-a — não crie uma busca manual ao lado delas. Elas fornecem cache, deduplicação, retries e cancelamento gratuitamente:
const { data, isLoading, error } = useQuery({
queryKey: ["article", id],
queryFn: ({ signal }) => fetchArticle(id, signal),
});
Construa o hook abaixo apenas quando o projeto não tiver uma camada de dados e você não quiser adicionar uma.
O hook tipado base (zero dependências)
// useFetch.ts
import { useEffect, useState } from "react";
type State<T> =
| { status: "loading"; data: null; error: null }
| { status: "success"; data: T; error: null }
| { status: "error"; data: null; error: Error };
export function useFetch<T>(url: string, init?: RequestInit): State<T> {
const [state, setState] = useState<State<T>>({
status: "loading",
data: null,
error: null,
});
useEffect(() => {
const controller = new AbortController();
setState({ status: "loading", data: null, error: null });
fetch(url, { ...init, signal: controller.signal })
.then(async (res) => {
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
return (await res.json()) as T;
})
.then((data) => setState({ status: "success", data, error: null }))
.catch((err: unknown) => {
if (err instanceof DOMException && err.name === "AbortError") return; // esperado
setState({
status: "error",
data: null,
error: err instanceof Error ? err : new Error(String(err)),
});
});
return () => controller.abort(); // cancelar ao desmontar / mudança de url
}, [url]); // reexecutar apenas quando a identidade da requisição mudar
return state;
}
Por que está correto:
- A união discriminada torna estados ilegais irrepresentáveis — você não pode ler
dataenquanto estiverloading. AbortController+ o cleanup retornado cancela a requisição anterior antes de iniciar uma nova, eliminando a race condition clássica onde respostas resolvem fora de ordem.- O ramo
AbortErrorpermanece silencioso, então um cancelamento normal nunca exibe um erro.
Usando-o — renderize todos os três estados
function Article({ id }: { id: string }) {
const result = useFetch<ArticleDto>(`/api/v1/articles/${id}`);
if (result.status === "loading") return <Spinner aria-label="Carregando artigo" />;
if (result.status === "error") return <ErrorBanner message={result.error.message} />;
return <ArticleView article={result.data} />;
}
Renderizar um branch de loading e erro não é um polimento opcional — é a diferença entre uma tela em branco e uma utilizável.
Erros comuns que este skill previne
useEffect(() => { fetch(url).then(r => r.json()).then(setData) }, [])— sem estado de loading, sem tratamento de erro, sem cancelamento, e[]ignora umaurlque muda.- Colocar valores não estáveis (um literal de objeto/array, um
initinline) no array de dependências, causando um loop infinito de refetch. Memorize-os ou dependa de primitivos. setDatadisparar após a desmontagem. Oabort()no cleanup faz com que o.thentardio interrompa noAbortError.- Engolir respostas não-2xx —
fetchsó rejeita em falha de rede, então você deve verificarres.okmanualmente.
Lista de verificação antes de considerar concluído
- A busca está em um hook; o componente apenas lê o estado.
- Loading, erro e dados estão todos representados e todos renderizados.
- A resposta é tipada (sem
any); não-2xx é transformado em erro. - Um
AbortControllercancela na desmontagem e quando as entradas mudam. - O array de dependências contém apenas valores estáveis que definem a requisição.
- Se o projeto tem React Query / SWR, este é usado no lugar deste hook.