Query libraries and dedupe

A query library is a cache keyed by a query key — the key is the whole mechanism. You don’t fetch into a component; you declare “this key maps to this fetcher”, and the library owns the cache entry. Every component that asks for the same key reads the same entry. That single idea is what gives you dedupe, sharing, and invalidation for free.

"use client";
import { useQuery } from "@tanstack/react-query";

function useUser(id: string) {
  return useQuery({
    queryKey: ["user", id],          // identity of the cached resource
    queryFn: () => fetch(`/api/users/${id}`).then((r) => r.json()),
    staleTime: 30_000,               // 30s: data is "fresh", no refetch
  });
}

Mount useUser("42") in three components and you do not get three requests. The library sees one in-flight promise for ["user","42"] and hands all three the same result. That is request deduplication, and it is the first thing you’d otherwise reinvent badly.

Background revalidation is stale-while-revalidate: serve the cached value instantly, refetch underneath, swap when fresh. Your component never blocks on a refetch it didn’t ask for. When a query goes stale (past staleTime) and something re-triggers it — a remount, a window refocus, a manual invalidate — the library returns the cached data immediately and fires a background fetch. The UI shows last-known-good data with zero spinner, then updates.

function UserName({ id }: { id: string }) {
  const { data, isPending, isFetching } = useUser(id);
  if (isPending) return <Skeleton />;          // first load, no cache yet
  // isFetching === true here means a *background* revalidation is running;
  // `data` is still the cached value, fully usable — no spinner needed
  return <span>{data.name}{isFetching && <Dot title="refreshing" />}</span>;
}

Note the two distinct states: isPending (no data at all, show a skeleton) versus isFetching (have data, refreshing in the background). Hand-rolled fetching collapses both into one loading boolean and flashes a spinner on every revalidation. The library separates them because they are different UX.

Mutations don’t write to the cache directly — they invalidate keys, and dependent reads revalidate themselves. After a write, the truth is on the server, so the correct move is to mark the affected query keys stale and let the library refetch. You declare which keys this mutation invalidates; everything reading those keys refreshes. You never manually reach into other components to “also update their copy”.

import { useMutation, useQueryClient } from "@tanstack/react-query";

function useRenameUser(id: string) {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: (name: string) =>
      fetch(`/api/users/${id}`, { method: "PATCH", body: JSON.stringify({ name }) }),
    onSuccess: () => {
      qc.invalidateQueries({ queryKey: ["user", id] });  // this user refetches
      qc.invalidateQueries({ queryKey: ["users"] });      // any list including them refetches
    },
  });
}

One invalidateQueries call fans out to every consumer of that key. There is no prop-drilling the new value, no Redux action rippling through reducers — the cache is the single source and invalidation is the single sync mechanism.

Retries and the failure axis come built in — and the failure mode of not using a library is duplicated server state. Query libraries retry failed fetches with backoff, expose error/isError, and let you tune retry count per query. You get a real error path, not a half-finished try/catch per component. But the deeper win is what you stop doing: the moment you copy a fetched response into useState or dispatch it into Redux, you’ve created a second source of truth that the server can invalidate at any time, and now you own the sync code that keeps drifting.

// ANTI-PATTERN: server data copied into client state, synced by hand
const [user, setUser] = useState<User | null>(null);
useEffect(() => { fetch(`/api/users/${id}`).then(r => r.json()).then(setUser); }, [id]);
async function rename(name: string) {
  await fetch(`/api/users/${id}`, { method: "PATCH", body: JSON.stringify({ name }) });
  setUser((u) => u && { ...u, name }); // optimistic guess — now this copy can drift from the server,
                                       // and any OTHER component holding its own copy won't update at all
}

That setUser is the trap: it’s a guess about server state, it doesn’t propagate to the other copies, and there’s no dedupe, no revalidation, no retry. The library replaces all of it with “read the key, invalidate the key”.