tanstack-query

Data handling with TanStack Query v5

@tanstack/react-query owns all client-side server state. React state is for UI state only (open/closed, selected tab, form draft). If a value came from the database, it lives in the Query cache — never in useState + useEffect.

Verified against @tanstack/[email protected].

Install

pnpm add @tanstack/react-query
pnpm add -D @tanstack/react-query-devtools @tanstack/eslint-plugin-query

The three-file convention per feature

src/modules/<feature>/
├── keys.ts        # query key factory — the single source of truth for keys
├── queries.ts     # queryOptions factories (reads)
├── mutations.ts   # mutationOptions factories (writes)
├── actions.ts     # 'use server' — the transport both of the above call
├── services/      # DB access (unchanged: services own the DB + business logic)
└── schemas/       # Zod schemas + z.infer types

Components never inline a queryKey or a queryFn. They import a factory.

1. Query keys — one factory, hierarchical

// modules/users/keys.ts
import type { ListUsersInput } from './schemas/user'

export const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: ListUsersInput) => [...userKeys.lists(), filters] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: string) => [...userKeys.details(), id] as const,
} as const

Rules:

• Hierarchical, general → specific. invalidateQueries({ queryKey: userKeys.lists() }) then hits every list regardless of filters, because invalidation is prefix-matched.
• Every variable the queryFn reads is in the key. A filter, page, or id that changes the response but not the key is a cache-poisoning bug.
• Serialisable values only — no class instances, no Date objects (use ISO strings).

2. Reads — queryOptions factories

queryOptions() is the "create options" helper: it keeps full type inference when options live outside the hook, and it ties the queryKey to its queryFn so queryClient.getQueryData(opts.queryKey) is typed with no annotation.