Chapter 76Lesson 2

The four primitives the project reaches for

The four core TanStack Query v5 hooks, useQuery, useMutation, useInfiniteQuery, and the optimistic update, written at the component call site.

The screen you are building is the per-invoice comment thread: live, optimistic, and infinitely scrollable. The previous lesson argued that a screen like this earns the library. This lesson shows you what you actually type.

It is a tour of the four primitives that thread is built from: useQuery to read, useMutation to write, the v5 decision about how to do an optimistic update, and useInfiniteQuery for the paginated thread itself. Around those four sits a small supporting cast that you’ll meet as each primitive needs it: query keys, the imperative cache calls, and polling.

One boundary is worth setting before the first line of code, because it explains every example that follows. This lesson teaches the call site: what you write inside a component once a cache already exists. It does not teach how that cache gets created and wired into the App Router, which is the next lesson’s whole job. So when an example calls useQuery with no provider in sight, that is not an omission: the provider lives one lesson away, and the call site is what we’re drilling here. By the end, all four primitives land together in one short component you could lift straight into the project.

`useQuery`: the read primitive

Start with the read hook, because it is the simplest of the four and every other primitive borrows its vocabulary.

A query is one idea: a read of server state, addressed by a key. You hand useQuery a key that identifies the data and a function that fetches it. In return, it hands you back the data plus a set of flags describing where the request is in its lifecycle.

const { data, error, isPending, isFetching } = useQuery({
  queryKey: commentKeys.lists(invoiceId),
  queryFn: () => fetchComments(invoiceId),
  staleTime: 60_000,
});

The destructured returns. data is the resolved value, or undefined before the first success; error is whatever the fetch threw; isPending and isFetching are the two flags we unpack next.

const { data, error, isPending, isFetching } = useQuery({
  queryKey: commentKeys.lists(invoiceId),
  queryFn: () => fetchComments(invoiceId),
  staleTime: 60_000,
});

The query key is the cache address. Two queries with the same key share one cache entry, and everything else in the library, refetching, invalidation, and optimistic writes, is addressed through this array. The next section is entirely about it.

const { data, error, isPending, isFetching } = useQuery({
  queryKey: commentKeys.lists(invoiceId),
  queryFn: () => fetchComments(invoiceId),
  staleTime: 60_000,
});

The fetcher. It returns a Promise that resolves to the data shape, or it throws, and a throw becomes the error above. It says nothing about where the data comes from; that’s the section after the keys.

const { data, error, isPending, isFetching } = useQuery({
  queryKey: commentKeys.lists(invoiceId),
  queryFn: () => fetchComments(invoiceId),
  staleTime: 60_000,
});

How long the cached data is treated as fresh. While it’s fresh, mounting the component or refocusing the tab will not refetch. We come back to why 60_000 rather than the library’s default in a moment.

1 / 1

That destructure is the whole API for a read. But two of those flags, isPending and isFetching, are the most confused pair in the library, and getting them right is the difference between a clean loading UX and a screen that flickers every time the user looks away and back.

`isPending` versus `isFetching`

They sound like synonyms, but they answer two completely different questions.

isPending asks: have I ever resolved? It is true only until the very first successful fetch, the state where there is no cached data yet and nothing to show. Once a query has resolved even once, isPending is false from then on, because the cache now holds something to render.

isFetching asks: is a request in flight right now? It is true during the first fetch, but also during every background refetch afterward: a poll firing, a window refocus, a manual invalidation. A query can have data sitting in the cache and still be isFetching while it checks for a fresher copy.

That split maps cleanly onto two different things you put on screen.

Moment

isPending

isFetching

What the user sees

First load cold — nothing cached yet

true

Skeleton

Idle, data fresh served from cache

false

The content, sitting still

Background refetch poll / refocus / invalidation

false

true

The content, quietly freshening

Two flags, two UI states. The skeleton is gated on isPending, a quiet in-place spinner on isFetching. They are never the same UI.

The rule follows from the split. Render the skeleton while isPending, because there is genuinely nothing to show. Render a subtle spinner or a slight dimming while isFetching: there is content on screen and you are just freshening it, and yanking it back to a skeleton would make a quiet background refetch feel like a full reload.

There is a third flag you’ll see in the docs. v5 also exposes isLoading, defined as exactly isPending && isFetching: first load, no cache, request in flight. It exists and it’s fine to use, but this course reaches for the two underlying flags because they map one-to-one onto the two UI states above. Build on isPending and isFetching, and treat isLoading as a convenience alias for the cold-load corner.

Why `staleTime: 60_000` and not the default

Now the staleTime line from the destructure, because the library’s default here is a trap for SaaS reads.

The default staleTime is 0. Zero means data is considered stale the instant it arrives, so every mount and every window focus fires a refetch. For a stock ticker or a live scoreboard, that is exactly right: you genuinely want the freshest number every time the component appears. For almost every SaaS read, it is wrong, and the symptom is a refetch storm: alt-tab away to read an email, come back, and the screen refetches every query it holds, for data that was perfectly current a few seconds ago.

The senior default flips it.

Library default (staleTime: 0)
Senior default (staleTime: 60_000)

useQuery({ queryKey, queryFn, staleTime: 0 });

Refetches on every mount and every focus. Data is stale the moment it lands, so remounting the component or refocusing the tab fires a fresh request each time. Correct for always-live data like a price ticker, but a refetch storm for a comment thread that changes a few times an hour.

useQuery({ queryKey, queryFn, staleTime: 60_000 });

Serves the cache for a minute, no thrash. For 60 seconds the cached data counts as fresh, so a remount or refocus reads straight from the cache with no network hit. The user still gets fresh data, because polling and explicit invalidation override staleness; they just stop paying for a refetch every time they glance away and back.

You’ll see 60_000 set once, on the QueryClient, in the next lesson, so it becomes the default for every query in the app rather than a line you remember to paste. At a single call site you override it only when that one query genuinely needs different freshness, and when you do, you leave a comment saying why.

One last thing about data before we move on, because it’s easy to get wrong. The data you destructure is not a copy; it is a direct reference into the cache. Mutate it in place with something like data.comments.push(newOne) and you have edited the cache behind the library’s back: no re-render fires, and the store is now in a state TanStack Query doesn’t know about. Treat data as frozen. When you need to change cached data, go through the cache’s own write calls, which we get to shortly.

Here are the two load-bearing config keys with their definitions inline:

const { data, error, isPending, isFetching } = useQuery({
  queryKey: commentKeys.lists(invoiceId),
  queryFn: () => fetchComments(invoiceId),
  staleTime: 60_000,
});

Query keys are the cache contract

We’ve now leaned on the query key twice and deferred it both times. It earns its own section, because the entire library hinges on key identity: refetching, invalidation, and the optimistic writes coming later are all addressed through this one array.

A query key is an array, and the convention is to make it hierarchical, broad on the left and specific on the right:

['comments'];
['comments', 'list', invoiceId];
['comments', 'detail', commentId];

The hierarchy is what makes invalidation ergonomic. When you tell the cache to invalidate ['comments'], it matches by prefix: every key that starts with ['comments'] is included, so the whole family refetches at once. Hand it the longer ['comments', 'list', invoiceId] instead and you’ve narrowed the scope to one invoice’s list, leaving every other comment query untouched. You pick how wide to reach by how much of the key you specify.

There is one real watch-out here. Keys are serialized internally so the cache can look them up, which means only serializable values belong in a key: strings, numbers, booleans, and plain objects. A Date, a function reference, a class instance, or a React component does not serialize stably, and putting one in a key quietly breaks the lookups that the whole library depends on. Use primitives and plain objects, nothing else.

Centralize the keys

Writing those arrays by hand at every call site is how a codebase drifts. One file types ['comments', 'list', id], another types ['comment', 'list', id], the invalidation silently misses, and you spend an afternoon learning that a typo’d string in an array doesn’t throw; it just fails to match.

The fix is a single typed helper per feature, so the raw arrays are written exactly once:

export const commentKeys = {
  all: ['comments'] as const,
  lists: (invoiceId: string) => [...commentKeys.all, 'list', invoiceId] as const,
  detail: (id: string) => [...commentKeys.all, 'detail', id] as const,
};

Now every call site reads commentKeys.lists(invoiceId) instead of an inline array. The read side and the write side reference the same function, so they cannot drift, and the as const keeps each key narrowly typed as a literal tuple rather than widening to string[].

If this shape feels familiar, it should. It is the same discipline as the cache-tag helper from the caching chapter: one source of truth for the strings that address a cache, so the code that fills the cache and the code that invalidates it can never disagree. The earlier chapter applied it to the Server Component cache; this is the identical pattern applied one layer over, to the client cache. You are not learning a new idea here, you are reusing one you already trust.

The mechanic to lock in is prefix matching, so try it. Below are several query keys. For each, decide whether invalidating ['comments', 'list', 'inv-1'] would refetch it, which comes down to a single question: does the key start with that exact prefix?

An invalidation of ['comments', 'list', 'inv-1'] matches a query only if its key starts with that exact prefix. Sort each key by whether it gets refetched. Drag each item into the bucket it belongs to, then press Check.

Refetched Key starts with ['comments', 'list', 'inv-1']

Untouched Different prefix — no match

['comments', 'list', 'inv-1']

['comments', 'list', 'inv-1', { sort: 'newest' }]

['comments', 'list', 'inv-2']

['comments', 'detail', 'cmt-9']

['comments']

['invoices', 'list', 'inv-1']

The chip worth pausing on is ['comments'] on its own. It is broader than the prefix you invalidated, not a descendant of it, and invalidating a child never reaches back up to the parent. Matching only ever flows from a shorter prefix down to the longer keys beneath it.

`queryFn`: what the cache reads from

The key says which data. The queryFn says how to get it. It is an async function that resolves to the data shape, or throws on failure, and as you saw, a throw lands in useQuery’s error, so failures become values you render rather than exceptions you chase.

The open question is what that function should actually call, and the course makes a deliberate decision.

The queryFn calls a route handler, not a Server Action.

const fetchComments = async (invoiceId: string, cursor: string | null) => {
  const res = await fetch(`/api/invoices/${invoiceId}/comments?cursor=${cursor ?? ''}`);
  if (!res.ok) throw new Error('Failed to load comments');
  return commentPageSchema.parse(await res.json());
};

The reason is a clean division of labor. Server Actions are built for form submissions: they carry redirect and revalidation semantics, and their error shape is tuned for “show this message under that field.” A read is none of those things. It wants stable HTTP status codes, it wants to be cacheable, and it wants a shape that any HTTP client could consume. That is exactly what a route handler is for, and you built them a few chapters back. The route handler is the seam between the client cache and the database, and as a bonus it doubles as a public contract: a future mobile app or a third-party integration hits the same URL.

State the split once and it covers every case you’ll meet:

TanStack Query reads from route handlers. Mutations can go either way: a route handler when you want the contract, a Server Action when you want the in-app shortcut.

The mutation side gets settled in the project lesson; for reads, it’s always the route handler.

Parse the response with Zod

Notice the last line of that fetcher: commentPageSchema.parse(...). That is not decoration; it is the thing that makes the cached data trustworthy.

The route handler validates its response against a Zod schema, the contract from the route handlers chapter. The queryFn parses the response it receives against that same schema. The schema lives in /lib, and both sides import it, so there is one definition rather than two that can drift.

The payoff is that cached data is typed by construction. If the server’s shape ever drifts from what the client expects, such as a renamed field or a missing key, the parse throws, and that throw surfaces as a useQuery error you can see and handle. Without the parse, the same drift is silent: TypeScript believes the data matches its type because you told it the fetch returns that type, and the mismatch only shows up later as a confusing runtime crash deep in your render.

One forward pointer so you’re not surprised in the next lesson: on the server, this same read runs the database query directly instead of fetching its own URL over the network. The function branches on whether it’s running in the browser, and both branches validate against the same schema. That branch is a wiring detail the next lesson covers; here, just hold that the schema is the shared contract on both sides.

`useMutation`: the write primitive and its lifecycle

Reads are done. Writes are the second primitive, and they are where the library gets genuinely interesting, because a write is not a single moment: it is a lifecycle with hooks you can attach behavior to.

Lead with the destructure:

const { mutate, mutateAsync, isPending, error } = useMutation({
  mutationFn: (input) => postComment(invoiceId, input),
  onMutate,
  onError,
  onSuccess,
  onSettled,
});

The shape rhymes with useQuery: a function that does the work (mutationFn instead of queryFn), and some flags. What’s new is the four callbacks, onMutate, onError, onSuccess, and onSettled, and they are the reason useMutation exists rather than you just calling the fetcher yourself.

The mutation lifecycle

A mutation moves through a fixed sequence, and each of its four callbacks fires at one specific point in it. The part that trips people up isn’t when each fires; it’s that onMutate and onError are connected. onMutate returns a value, and that value is handed to onError. That handoff is the rollback channel, and it’s the piece you have to see to understand optimism.

Walk the sequence: