server-state

TanStack Query

Setup

• QueryProvider (src/providers/QueryProvider.tsx) creates the browser QueryClient once.

• The router context owns the QueryClient (src/providers/root-provider.ts, wired in src/router.tsx).

• Defaults live in makeQueryClient() (src/lib/query-client.ts). Never create a module-level QueryClient.

Rules

• Key factory per feature in api/query-keys.ts (all, lists(), list(filters), details(), detail(id), as const). Page and filters belong in the key.
• Define each query once with queryOptions() in api/; reuse it in hooks, prefetching, loaders and setQueryData.
• Components call a thin hook from hooks/ (useUsers), never useQuery directly.
• Pass the query function's signal to the api function.
• Mutation hooks invalidate the affected keys in onSettled.
• Optimistic updates only when the UX needs them: render mutation.variables while pending; use onMutate with rollback only when several components must show the change.
• Server data stays in the Query cache. Never copy it into a Zustand store.

import { getUsers } from "@/features/users/api/get-users.api"; import { userKeys } from "@/features/users/api/query-keys";

export const usersQueryOptions = (page: number) => queryOptions({ queryKey: userKeys.list({ page }), queryFn: ({ signal }) => getUsers(page, signal), });

```ts
// features/users/hooks/use-users.ts
import { useQuery } from "@tanstack/react-query";

import { usersQueryOptions } from "@/features/users/api";

export function useUsers(page: number) {
  return useQuery(usersQueryOptions(page));
}