TanStack data loading

The first argument selects the mode. With no mode argument, infer it: a request to audit, find waterfalls or review existing code is

audit

; a request to rediscover or bust the cache is

refresh

; anything else is writing.

```
audit [--fix] [path]
```
— read references/audit.md before starting, and run it over
```
path
```
.
```
refresh [path]
```
— rerun Discovery for the app containing
```
path
```
, write the result, and stop.
Writing — apply the rules below to the code being written or reviewed, within
```
path
```
if given.

Every mode starts with Discovery. The rules branch on what it records: if you guess the backend shape, you apply the wrong server function rules and the wrong write rules.

Available scripts

scripts/discovery.py
—
```
read
```
and
```
write
```
the discovery cache at
```
<repo-root>/.draekien/tanstack-data-loading/discovery.json
```
, one discovery entry per app root;
```
versions
```
prints the installed
```
@tanstack
```
versions.
```
--help
```
lists the exit codes.

Discovery

App root. The nearest ancestor of

path

(or of the current directory) whose

package.json

depends on

@tanstack/react-start

. If none matches, or the task spans several apps, ask the user which app.

Read. Run the script from this skill's directory, passing the app root relative to the repo root (

for a single-package repo):

bash

uv run scripts/discovery.py read --app apps/web --repo <repo-root>

Exit	Meaning	Next
0	Fresh discovery entry printed	Use it, and apply its `versionNotes` in place of the rules they name. In `refresh` , discover and write anyway.
4	No discovery entry	Discover and write.
5	Older than the script's maximum age, or an installed `@tanstack` version changed	Discover and write.
3	Cache file or an installed package manifest unreadable	Read stderr. For the cache file, tell the user and delete it only after they agree, since it holds every app's discovery entry. For a manifest, ask the user to reinstall dependencies.
2	Usage error	Read stderr, correct the call, rerun.

Discover. Find each field from the code:

Field	Values	How to find it
`backend`	`database` , `service` , `both`	Read the `createServerFn` handlers. `database` : they query a database client directly. `service` : they call another service over HTTP. `both` : some do each.
`pendingUi`	`route-level` , `per-section`	`route-level` when the router sets `defaultPendingComponent` . Otherwise ask the user whether they want a route-level pending component or Suspense sections only; with no user available, record `per-section` and say so.
`verify`	list of commands	The repo's lint, typecheck and test commands from `package.json` `scripts` .
`versionNotes`	list of strings	Run `uv run scripts/discovery.py versions --app <app-root> --repo <repo-root>` and compare against Versions. When it sends you to references/versions.md, record its findings, or `checked: no changes` when there are none. Otherwise empty. If `versions` prints `{}` , ask the user to install dependencies before continuing.

Write. The script adds

discoveredAt

and the installed

versions

, and rejects unknown values:

bash

uv run scripts/discovery.py write --app apps/web --repo <repo-root> <<'EOF'
{"backend": "database", "pendingUi": "per-section", "verify": ["pnpm check", "pnpm typecheck", "pnpm test"], "versionNotes": []}
EOF

First write in a repo. Exit 6 means

.draekien/

is missing: ask the user before creating it. When

.draekien/tanstack-data-loading/discovery.json

does not exist yet, ask whether to add

.draekien/tanstack-data-loading/

.gitignore

; the discovery entries hold one developer's local discovery. If the user declines

.draekien/

, keep the discovered fields for this task only and say the discovery cache was not written.

Discovery is done when

read

write

exits 0 for the app, or when the user declined the cache and every field is known.

Backend rules. Before writing or auditing any server function, mutation or write path, read the reference for

backend

```
database
```
— references/backend-database.md.
```
service
```
— references/backend-service.md.
```
both
```
— read both. Apply each to the server functions whose handlers match it; a handler that does both applies each reference to its own part.

Versions

Rules were checked against

@tanstack/react-query

5.104.2,

@tanstack/react-router

1.170.44 and

@tanstack/react-start

1.169.1. Before applying a rule that uses an API below, compare the installed versions (the discovery entry's

versions

, or the

versions

command) to the minimum and use the substitute when the installed version is lower:

Rule uses	Needs	Below the minimum
`queryClient.query` , `queryClient.infiniteQuery`	`@tanstack/react-query` 5.102.0	`fetchQuery` , `prefetchQuery` , `ensureQueryData` and their infinite variants, which are not deprecated there
`staleTime: "static"`	`@tanstack/react-query` 5.79.0	`ensureQueryData(options)` , which behaves the same in a loader
`import { noop } from "@tanstack/react-query"`	`@tanstack/react-query` 5.76.0	`.catch(() => {})`
mutation `scope: { id }`	`@tanstack/react-query` 5.32.0	disable the trigger while `isPending`
`createServerFn().validator(...)`	`@tanstack/react-start` 1.168.25	`.inputValidator(...)` ; versions from 1.169.0 accept only `.validator(...)`
`*.server.ts` blocked from client imports	`@tanstack/react-start` 1.166.8	the suffix is a naming convention; nothing blocks the import

When an installed major version is newer than the checked one, or an API a rule uses is missing from the installed types, and the discovery entry has no

versionNotes

, read references/versions.md before applying any rule.

Loaders

Scope: the

loader

option of every file route under the app root.

A read is critical when the route must not render without it or must render something else when it fails: the main content, existence (404), authorization (403), a redirect, a limit gate, form defaults. Every other read is unawaited.

Critical read:
```
await context.queryClient.query(options)
```
. Awaiting it in the loader sends a 404 or 403 to
```
notFoundComponent
```
or
```
errorComponent
```
before render; let the error reach them, or throw
```
notFound()
```
.
Unawaited read, including hidden variants such as a toggle's second period:
```
void context.queryClient.query(options).catch(noop)
```
. Without
```
.catch(noop)
```
the rejection is unhandled on the server; the component's
```
useSuspenseQuery
```
still rethrows the error to its boundary.
Start every unawaited read before the first
```
await
```
. A read started after an
```
await
```
is a waterfall.

Independent critical reads: one

await Promise.all([...])

✗ await context.queryClient.query(orderQueryOptions(id))
  await context.queryClient.query(customerQueryOptions(customerId))

✓ await Promise.all([
    context.queryClient.query(orderQueryOptions(id)),
    context.queryClient.query(customerQueryOptions(customerId)),
  ])

A read

that needs read

's result is a waterfall that cannot be removed:

`a`	`b`	Loader
critical	critical	`const x = await query(a)` , then `await query(b(x))`
critical	unawaited	`const x = await query(a)` , then `void query(b(x)).catch(noop)` : the one unawaited read started after an `await`
unawaited	unawaited	`void query(a).then((x) => query(b(x))).catch(noop)` , started before the first `await`

The loader and the component use the same
```
queryOptions
```
object. A different key in the component fetches the data a second time.
A route a signed-out visitor can open starts reads that require a session only in its signed-in branch. Otherwise every signed-out visit fires calls that throw.

Replace deprecated

QueryClient

methods:

Deprecated	Replacement
`fetchQuery(options)`	`query(options)`
`prefetchQuery(options)`	`void query(options).catch(noop)`
`ensureQueryData(options)`	`query({ ...options, staleTime: "static" })` , which behaves the same. If a mutation invalidates the key, use `staleTime: Infinity` instead: a later loader run with `"static"` returns the invalidated cached data, so the route decides its branch, redirect or gate from old data, while `Infinity` refetches first. A `staleTime` passed to one `query()` call does not stay on the query: whether invalidation refetches a mounted page depends on the component's `useSuspenseQuery` `staleTime`
`fetchInfiniteQuery(options)`	`infiniteQuery(options)`
`prefetchInfiniteQuery(options)`	`void infiniteQuery(options).catch(noop)`
`ensureInfiniteQueryData(options)`	`infiniteQuery(...)` with the same `staleTime` choice as `ensureQueryData`

Do not defer reads to scroll or interaction, and do not add hover prefetching beyond the router's
```
defaultPreload: "intent"
```
. An unawaited read already streams without blocking the page; deferring it adds a request after render, and no TanStack doc defines how deferral behaves with
```
useSuspenseQuery
```
.

Streaming and SSR

Scope: the router file and every route's

ssr

option.

The rules here hold only when the router file calls
```
setupRouterSsrQueryIntegration
```
from
```
@tanstack/react-router-ssr-query
```
. If it does not, report that as the first finding.
An unawaited read runs on the server and streams to the client without blocking the server response. A critical read blocks the response until it resolves.
```
useSuspenseQuery
```
and loader reads run on the server.
```
useQuery
```
does not; its data loads after hydration, so a route component that reads with
```
useQuery
```
is a waterfall.
```
ssr: "data-only"
```
runs
```
beforeLoad
```
and
```
loader
```
on the server and renders the component only on the client. Do not rely on unawaited reads streaming under
```
ssr: "data-only"
```
, and do not recommend it as a fix; no official doc states the behaviour. Check it in the running app when the task depends on it.
Do not configure route code splitting: Start always enables it, and the loader stays in the main chunk.

Components

Scope: components that read query data with suspense.

Two or more suspense queries in one component: one

useSuspenseQueries

call. Separate

useSuspenseQuery

calls in one component are a waterfall: the second starts after the first resolves.

tsx

✗ const { data: order } = useSuspenseQuery(orderQueryOptions(id))
  const { data: notes } = useSuspenseQuery(notesQueryOptions(id))

✓ const [{ data: order }, { data: notes }] = useSuspenseQueries({
    queries: [orderQueryOptions(id), notesQueryOptions(id)],
  })

A child that suspends on a query its route could know about: start that read in the route loader. Otherwise the child's request starts only after the parent renders.
Each unawaited read renders inside its own Suspense section:
```
<CatchBoundary getResetKey={...} errorComponent={...}>
```
from
```
@tanstack/react-router
```
around
```
<React.Suspense fallback={...}>
```
, inside
```
QueryErrorResetBoundary
```
where the error UI offers a retry. The rest of the page renders while the section streams, and its error stays inside it. A critical read needs no Suspense section.
A query key that changes on the same route (search param, tab, page, period): make the change inside
```
React.startTransition
```
.
```
useSuspenseQuery
```
has no
```
placeholderData
```
; without the transition, React replaces the content with the fallback.
```
pendingUi: route-level
```
: the router sets
```
defaultPendingComponent
```
, rendered inside the app's shell layout. It renders after
```
defaultPendingMs
```
(default 1000) and stays at least
```
defaultPendingMinMs
```
(default 500).
```
pendingUi: per-section
```
: add no
```
defaultPendingComponent
```
; if the user chose this while the router sets one, leave it until they ask for its removal.

Mutations

Scope: every

useMutation

The server function returns the saved entity.
```
onSuccess
```
writes it with
```
queryClient.setQueryData(key, saved)
```
.

onSuccess

invalidates only keys derived from the change (lists, counts, totals) and does not await the invalidation. A promise returned or awaited in

onSuccess

keeps

isPending

true until every invalidated query has refetched.

✗ onSuccess: async () => {
    await queryClient.invalidateQueries({ queryKey: orderKeys.all })
  }

✓ onSuccess: (saved) => {
    queryClient.setQueryData(orderKeys.detail(saved.id), saved)
    void queryClient.invalidateQueries({ queryKey: orderKeys.lists() })
  }

Never invalidate the key just written; invalidation refetches it. To invalidate a prefix that contains it, skip the written key with a

predicate

void queryClient.invalidateQueries({
  queryKey: orderKeys.all,
  predicate: (query) =>
    query.queryKey.length !== written.length ||
    query.queryKey.some((part, index) => part !== written[index]),
})

Saves to one entity that can overlap (autosave, rapid toggles): set
```
scope: { id }
```
to a string naming the entity, such as
```
`order-${orderId}`
```
. Mutations with the same
```
scope.id
```
run one at a time in call order. A refetch after each save does not fix ordering: the responses can still arrive out of order.
A mutation that changes which data the user may see (switching account or workspace) awaits its invalidation, so the next screen never renders with the previous account's data. Every other mutation follows the rule above.

Server functions

Scope: every

createServerFn

Put
```
createServerFn
```
exports in
```
*.functions.ts
```
. Client code may import them; the build replaces each handler with a request stub. Server-only helpers go in
```
*.server.ts
```
, which import protection blocks from client code.
Validate input:
```
.validator(z.object({ ... }))
```
.
Each call from the client is one HTTP request with a fixed cost: the request, plus every middleware it runs. Start neither batches nor deduplicates calls:
```
Promise.all
```
over three server functions sends three concurrent requests, and two identical calls send two. Deduplicate identical reads through the query cache by calling the server function only from a
```
queryFn
```
.
Do not merge every read on a page into one server function. The page then waits for its slowest part, Suspense sections stop streaming separately, and every mutation refetches all of it.
Middleware runs on every call to every server function that uses it. Shared middleware computes only what every one of those functions reads; a value only some read goes in its own middleware.
Statements sent on one database connection, including every statement in one transaction, run one at a time.
```
Promise.all
```
over them saves no time; reduce the number of statements instead.
Apply the backend reference named under Discovery, "Backend rules", to every server function.

Gotchas

```
useSuspenseQueries
```
does not accept infinite queries. An infinite query in the same component still starts after the others resolve; start it in the loader.

After converting to

useSuspenseQueries

, every test mock of

@tanstack/react-query

must export

useSuspenseQueries

```
toBe
```
on cached rows fails: structural sharing returns an equal copy, not the same object. Use
```
toEqual
```
.
Once a loader awaits a read, a 404 from it right after a write (a backend that updates its read model asynchronously) shows the route's error component instead of an error inside a Suspense section.

tanstack-data-loading

NPX Install

Tags

SKILL.md Content