Query keys: the cache's identity

TanStack Query (this track targets v5) keeps one cache per QueryClient. Picture a map: each entry is filed under the hash of a query key and holds that query's data, error and status. When a component calls useQuery({ queryKey, queryFn }), the library:

1. hashes queryKey and looks up that entry;
2. returns whatever data the entry already has, straight away;
3. runs queryFn if the entry has no data yet (or its data is stale), and stores the result under that key.

The queryFn is not part of the identity. It is only "how to fill this entry". So two calls with the same key are one entry, whatever their functions do:

function OpenTodos() {
  const { data } = useQuery({ queryKey: ["todos"], queryFn: () => fetchTodos("open") });
  return <TodoList todos={data} />;
}

function DoneTodos() {
  const { data } = useQuery({ queryKey: ["todos"], queryFn: () => fetchTodos("done") });
  return <TodoList todos={data} />;
}

Render both on one page and only one request goes out — the library dedupes fetches for the same key — so both components show the same list: whichever one mounted first ran its queryFn (with OpenTodos first, the open todos), and the second queryFn didn't run at all.

The rule that prevents this is the one the docs state outright: if the queryFn reads a variable, the variable goes in the key.

// ❌ status changes, the key doesn't: same entry, no new request
useQuery({ queryKey: ["todos"], queryFn: () => fetchTodos(status) });

// ✅ one entry per status
useQuery({ queryKey: ["todos", { status }], queryFn: () => fetchTodos(status) });

With status in the key, the key behaves like a dependency array. Change status and the hook moves to a different entry: if that entry already has data you see it immediately, and if it has none (or it's stale) the queryFn runs and fills it.

Two shape rules: the key must be an array at the top level (since v4), and everything in it must be serialisable with JSON.stringify.

Once a feature has a list, a filtered list and a detail view, hand-written keys drift: one file writes ["todo", id], another ["todos", "detail", id], and an invalidation misses one of them. The fix is to spell every key in one place, general → specific:

type TodoFilters = { status: "open" | "done"; page: number };

export const todoKeys = {
  all: ["todos"] as const,
  lists: () => [...todoKeys.all, "list"] as const,
  list: (filters: TodoFilters) => [...todoKeys.lists(), filters] as const,
  details: () => [...todoKeys.all, "detail"] as const,
  detail: (id: number) => [...todoKeys.details(), id] as const,
};

Line by line:

• all is the root. Every todo key starts with it, so one prefix reaches the whole feature.
• lists() and details() are the branches. They exist mostly to be matched: you rarely query ["todos", "list"] itself, but you will invalidate it.
• list(filters) ends with the filter object, so every input of fetchTodos(filters) is in the key, and property order doesn't matter.
• as const keeps each key a readonly tuple type instead of string[], which helps when you pass it around typed.

Keys are matched as prefixes, element by element from the start. That's how invalidateQueries, removeQueries and the other filter-taking methods decide what to touch:

["todos"] does not match ["user", "todos"] (position 0 differs) or ["todos-archive"] (strings aren't prefix-matched). Add exact: true when you mean only the key itself.

Co-locating the key with its function

The key and the queryFn must stay in sync, so v5's queryOptions helper lets you define them together. At runtime it returns what you pass in; in TypeScript it ties the data type to the key:

import { queryOptions } from "@tanstack/react-query";

export const todoQueries = {
  list: (filters: TodoFilters) =>
    queryOptions({ queryKey: todoKeys.list(filters), queryFn: () => fetchTodos(filters) }),
  detail: (id: number) =>
    queryOptions({ queryKey: todoKeys.detail(id), queryFn: () => fetchTodo(id) }),
};

// in a component
const { data } = useQuery(todoQueries.detail(id));
// elsewhere — the same key, typed: data is inferred as a Todo
queryClient.setQueryData(todoQueries.detail(id).queryKey, updatedTodo);

Components never spell a key again; they ask the factory. The next units lean on this: an invalidation after a save is one line, and it can't miss a variant.

A key is wrong in one of two directions. Too coarse: two different pieces of data share an entry (the missing-variable bug). Too fine: one piece of data is spread over several entries, or the key changes when the data didn't. The coarse kind shows wrong data; the fine kind shows stale data, duplicate requests, or a request loop.

"5" is not 5

The list renders rows with numeric ids. The detail route reads its id from the URL, where everything is a string:

// list row: prime the detail cache so the detail page opens instantly
queryClient.setQueryData(todoKeys.detail(todo.id), todo); // ["todos", "detail", 5]

// detail route, key written by hand
const { id } = useParams(); // "5"
useQuery({ queryKey: ["todos", "detail", id], queryFn: () => fetchTodo(id) }); // another entry

The detail page never sees the primed data, fetches again, and a later invalidateQueries({ queryKey: todoKeys.detail(5) }) misses it. Normalise at the boundary (Number(id)) and go through the factory, whose id: number parameter makes TypeScript refuse the string.

A value that changes every render

const since = new Date().toISOString(); // ❌ a new value on every render
useQuery({ queryKey: ["feed", { since }], queryFn: () => fetchFeed(since) });

Each response re-renders the component a few milliseconds later, which builds a new key, so a new entry and another request. Run headlessly against a fake fetch that takes 20 ms, this made 44 requests and 44 cache entries in one second, and it doesn't stop. Fix the value once (in state, or let the server decide what "latest" means) — a key holds inputs, not clocks.

Values JSON can't represent

The hash comes from the key's JSON form (with object keys sorted), so non-JSON values collapse:

• Map and Set hash as {} — every Set-valued key is the same entry. Pass [...selectedTags].sort() instead.
• undefined inside an array hashes as null, so ["todos", undefined] and ["todos", null] are one entry. (Inside an object, an undefined property is dropped.)
• A Date hashes as its ISO string, which is fine for a fixed date and fatal for new Date().

Prefixes reach into objects

Matching is partial inside objects too: ["todos", "list", { status: "open" }] matches ["todos", "list", { status: "open", page: 2 }]. That's handy — "every page of open todos" — and it means a filter object that's a subset of another is a prefix of it.

What does not go in the key

The docs' rule is "every variable the queryFn uses that changes." The function you call and a stable API client are not data inputs. @tanstack/eslint-plugin-query has an exhaustive-deps rule that flags a missing variable — the lint version of this whole unit — with an allowlist for things like an API client.