English for TanStack Query Developers

TanStack Query (formerly React Query) has become the standard way to manage server state in React applications, handling caching, background refetching, and synchronisation. If you work with TanStack Query on an international team, you’ll need clear English to describe caching behaviour, invalidation, and mutation flows. This guide covers the core vocabulary for TanStack Query developers.

Key Vocabulary

Query — a declarative request for asynchronous data, identified by a unique key, that TanStack Query caches and manages automatically. “We defined a query for the user’s profile, keyed by ['user', userId], so it’s cached and shared across every component that needs it.”

Query key — the unique identifier used to cache, retrieve, and invalidate a specific query’s data. “We include the filter parameters in the query key, so changing a filter automatically triggers a new, separately cached request.”

Mutation — an operation that creates, updates, or deletes data on the server, as opposed to a query, which only reads data. “We use a mutation to submit the form, and on success we invalidate the related query so the UI reflects the new data.”

Stale time — the duration for which cached data is considered fresh and won’t trigger a background refetch. “We set a five-minute stale time on the pricing query since prices rarely change and we don’t need to refetch on every render.”

Cache time (gcTime) — how long unused query data stays in memory before being garbage collected. “We increased the cache time for search results so navigating back to a previous search doesn’t require a full refetch.”

Invalidation — explicitly marking cached query data as stale, forcing a refetch the next time it’s needed. “After a successful mutation, we invalidate the todos query so the list refreshes with the newly created item.”

Optimistic update — updating the local cache immediately, before the server confirms the change, to make the UI feel instantaneous. “We use an optimistic update when a user likes a post, so the like count changes instantly instead of waiting for the network round trip.”

Background refetch — TanStack Query automatically re-fetching data behind the scenes, for example when a window regains focus. “Background refetch on window focus keeps the dashboard accurate if a user switches tabs and comes back later.”

Query invalidation cascade — the pattern of invalidating multiple related queries after a single mutation to keep all dependent views consistent. “Deleting a project triggers a cascade that invalidates the project list, the dashboard summary, and the recent-activity feed.”

Discussing Caching Strategy

• “We set a longer stale time on reference data, like country lists, since it changes so rarely.”
• “The query key includes the pagination page number, so each page is cached independently and switching pages feels instant.”
• “We disabled background refetch on this particular query because it caused a jarring layout shift for users.”

Talking About Mutations and Consistency

• “We roll back the optimistic update if the mutation fails, so the UI never shows a permanent lie about the server state.”
• “Invalidating the exact query key, rather than the whole cache, keeps unrelated parts of the UI from unnecessarily refetching.”
• “We use onSettled to invalidate regardless of success or failure, since either outcome could mean the server state changed.”

Professional Tips

1. Choose stale time deliberately, not by default. Explain to reviewers why a query is fresh for five minutes versus refetched on every mount.
2. Scope invalidation precisely. Invalidating too broadly causes unnecessary network traffic; invalidating too narrowly leaves stale data on screen.
3. Always handle the rollback path for optimistic updates. A failed mutation without rollback logic leaves the UI showing incorrect data.

Practice Exercise

1. Explain to a teammate, in 3-4 sentences, the difference between stale time and cache time.
2. Write a short explanation (4-5 sentences) of why you used an optimistic update for a “like” button but not for a payment submission.
3. Describe, in plain English, a bug caused by over-broad query invalidation, and how you narrowed the query key to fix it.