Query libraries: queryKey identity, the two clocks, and what TanStack Query actually saves you

queryKey is cache identity, not a label

The mental shift: server data is not your state — it is a cache of someone else’s state. TanStack Query makes that explicit. Every query is identified by its queryKey, an array hashed structurally (object key order does not matter, array order does): ['todos', { status, page }]. The key is the cache’s address. Every component calling useQuery with the same key reads the same cache entry — six components asking for ['me'] produce one request, deduplicated in flight, and one shared answer. The discipline that follows: every variable your queryFn reads must be in the key, exactly like a useEffect dependency array. Leave page out of the key and page 2 overwrites page 1 under the same address; the symptom is “wrong data flickers in”, the diagnosis is almost always a key that under-describes the request.

function Todos({ status, page }) {
  const { data, isPending, isError, error } = useQuery({
    queryKey: ["todos", { status, page }],   // identity = all inputs
    queryFn: ({ signal }) =>
      fetchTodos({ status, page, signal }),  // abort wired for free
    staleTime: 30_000,                        // fresh for 30s
  });
  // isPending → first load, no cached data yet
  // data can be present *and* stale: shown instantly, refetched behind
}

function AddTodo() {
  const queryClient = useQueryClient();
  const mutation = useMutation({
    mutationFn: createTodo,
    onSuccess: () =>
      queryClient.invalidateQueries({ queryKey: ["todos"] }), // prefix match
  });
  return <button onClick={() => mutation.mutate({ title: "ship" })}>Add</button>;
}

The two clocks: staleTime decides refetching, gcTime decides memory

Two independent timers govern every cache entry, and conflating them is the number-one TanStack Query misunderstanding. staleTime answers “is this data fresh enough to serve without asking the server again?” While an entry is fresh, any mount or focus event serves it from cache, full stop — zero requests. Once it goes stale, the data is still served instantly, but a background refetch fires on the next trigger: a new component mounting, the window regaining focus, the network reconnecting. That is stale-while-revalidate: the user always sees data immediately; freshness arrives quietly behind it. gcTime answers a different question: “after the last component using this entry unmounts, how long do we keep it in memory?” An active entry is never collected; an inactive one survives gcTime (default 5 minutes) so that navigating back within that window is an instant cache hit instead of a spinner.

The defaults are deliberately aggressive: staleTime: 0 — everything is stale immediately, so every mount and every window focus triggers a background refetch; plus failed queries retry 3 times with exponential backoff. Teams discover this as “why is my API getting hammered?” — the answer is not to disable refetchOnWindowFocus globally (that focus refetch is what keeps a dashboard truthful when the user comes back from lunch) but to set staleTime honestly per resource: 30 seconds for a todo list, 10 minutes for a country list, 0 for a stock price. The two clocks fail differently when misconfigured: staleTime too high serves wrong data; gcTime too high holds dead data in memory; setting gcTime lower than staleTime quietly defeats the point, since the entry is collected before its freshness ever matters to a returning visitor.

Mutations close the loop — and the library’s real invoice

Reads are half the story. useMutation wraps a write and, in onSuccess, you reconcile the cache with the new server reality — most simply with invalidateQueries({ queryKey: ['todos'] }), which prefix-matches every key starting with 'todos', marks them stale, and immediately refetches the active ones (inactive entries just get the stale flag and refetch on next use). This is the piece the effect pattern never had: after a POST, your hand-rolled useState caches across five components are all silently wrong, and no amount of effect hygiene fixes data that no longer reflects the server.

Tally what the library actually saves versus last lesson’s baseline: in-flight deduplication (six subscribers, one request) and shared cache entries; the race guard built in — responses are matched to their request, and queryFn receives an AbortSignal wired to query cancellation; retries with exponential backoff; lifecycle — staleness, focus/reconnect refetch, garbage collection; and the write path — invalidation, plus optimistic updates (next lesson). Together, these five properties mean that every component reading the same data stays synchronized across writes, network hiccups, and tab re-focuses without a line of boilerplate — drop any one of them and you are back to writing it yourself. The honest costs: a dependency in the critical path (~12 kB gzipped core), key-design discipline (keys are your cache schema — centralize them in a factory, because scattered ad-hoc keys make targeted invalidation guesswork), and defaults you must consciously tune. The tradeoff is the same one as ever: you are not avoiding a cache — you are choosing between a tested one and the one you will write by accident.