TanStack
Read the reference matched by the API or behavior being changed. Load adjacent references only for concerns the change crosses; reuse relevant context already read.
Branches
| When you are… |
Reference |
| Defining or changing query keys / factories |
references/query-keys.md |
| Setting staleTime, gcTime, invalidation, placeholder/initial data |
references/query-caching.md |
| Writing mutations, optimistic updates, or mutation state |
references/query-mutations.md |
| Prefetching, parallel queries, infinite queries, or cancellation |
references/query-fetch-patterns.md |
| SSR dehydrate/hydrate, offline networkMode, or query persistence |
references/query-ssr-offline.md |
| Query error boundaries or select/performance |
references/query-errors-performance.md |
Registering the router, from typing, virtual routes, or router defaults |
references/router-type-and-org.md |
| Route loaders, ensureQueryData, or parallel route loading |
references/router-data-loading.md |
| Search params, Link/navigate, route masks, or preload |
references/router-search-nav.md |
| Lazy routes, not-found, route context, or auth beforeLoad |
references/router-split-errors-context.md |
| TanStack Form hooks, Zod validators, or field components |
references/form.md |
Apply the technical rules relevant to the changed behavior.
Tripwires
Query — array keys that include every dependency; reconcile mutations through canonical keys: update from authoritative responses or invalidate when the owning read model requires a server reread; optimistic cache writes need rollback; never put non-serializable values in keys.
Router — register the router type; validate search with defaults (.catch()); use ensureQueryData in loaders when pairing with Query; throw redirect(...) not return.
Form — complete defaultValues for inference; Zod at form/field level; debounce async validators to fit endpoint cost and interaction needs; role="alert" on field errors; preventDefault on submit.
1---2name: tanstack3description: TanStack Query, Router, and Form patterns for React. Use when writing useQuery/queryOptions, mutations, caching, file-based routes, search params, loaders, or TanStack Form validation. Don't use for TanStack Start, TanStack DB/collections, Zustand client state, or non-TanStack routing.4---56# TanStack78Read the reference matched by the API or behavior being changed. Load adjacent references only for concerns the change crosses; reuse relevant context already read.910## Branches1112| When you are… | Reference |13| --- | --- |14| Defining or changing query keys / factories | `references/query-keys.md` |15| Setting staleTime, gcTime, invalidation, placeholder/initial data | `references/query-caching.md` |16| Writing mutations, optimistic updates, or mutation state | `references/query-mutations.md` |17| Prefetching, parallel queries, infinite queries, or cancellation | `references/query-fetch-patterns.md` |18| SSR dehydrate/hydrate, offline networkMode, or query persistence | `references/query-ssr-offline.md` |19| Query error boundaries or select/performance | `references/query-errors-performance.md` |20| Registering the router, `from` typing, virtual routes, or router defaults | `references/router-type-and-org.md` |21| Route loaders, ensureQueryData, or parallel route loading | `references/router-data-loading.md` |22| Search params, Link/navigate, route masks, or preload | `references/router-search-nav.md` |23| Lazy routes, not-found, route context, or auth beforeLoad | `references/router-split-errors-context.md` |24| TanStack Form hooks, Zod validators, or field components | `references/form.md` |2526Apply the technical rules relevant to the changed behavior.2728## Tripwires2930**Query** — array keys that include every dependency; reconcile mutations through canonical keys: update from authoritative responses or invalidate when the owning read model requires a server reread; optimistic cache writes need rollback; never put non-serializable values in keys.3132**Router** — register the router type; validate search with defaults (`.catch()`); use `ensureQueryData` in loaders when pairing with Query; `throw redirect(...)` not `return`.3334**Form** — complete `defaultValues` for inference; Zod at form/field level; debounce async validators to fit endpoint cost and interaction needs; `role="alert"` on field errors; `preventDefault` on submit.
pedronauck