---
description: TanStack Query ownership for kitcn cRPC queries, mutations, live Convex subscriptions, RSC preloading, cache keys, and bounded invalidation.
name: react-query
metadata:
  skiller:
    source: .agents/rules/react-query.mdc
---

# TanStack Query And cRPC

## Default

Use generated cRPC query and mutation options as the owner of query keys,
functions, input typing, and result typing. Do not hand-build parallel keys or
duplicate the transport contract in components.

Convex-backed cRPC queries are live subscriptions unless the API explicitly
documents a non-live path. A successful mutation normally updates subscribed
queries through Convex; blind invalidation is redundant and can cause churn.

## Colocation

- Keep a query in the smallest component or hook that owns its loading, empty,
  error, permission, and success states.
- Hoist only when siblings share the same result or a route owns preload.
- Keep presentation components data-agnostic when that improves reuse.
- Use component colocation rules before inventing a feature-wide data layer.

## Query Pattern

```tsx
const result = useQuery(
  crpc.projects.list.queryOptions({ workspaceId }),
);
```

Use `skipToken`, an explicit enabled condition, or the generated auth-aware
option when required input or session authority is missing. Do not send fake
identifiers to keep a hook unconditional.

## Mutation Pattern

```tsx
const createProject = useMutation(
  crpc.projects.create.mutationOptions({
    onSuccess: (project) => {
      router.push(`/projects/${project.id}`);
    },
  }),
);
```

Own user feedback at the mutation boundary. Disable duplicate submission,
surface the actual error, and preserve form input on failure.

Do not invalidate a live cRPC query by habit. Invalidation is allowed only when
the consumer is demonstrably non-subscribed, the source is HTTP/external, a
manual cache entry was written, or a server-side/RSC snapshot needs a bounded
refresh. Name that exception beside the code.

## RSC And Preload

- Prefer server callers for server-owned rendering and authorization.
- Use the package's supported preload/hydration path when a client component
  must adopt server-fetched data.
- Never create a second query-key dialect for RSC.
- Treat server snapshots and live client subscriptions as different lifetimes;
  document which one owns freshness.
- Avoid importing client-only Query machinery into Convex functions or other
  server-only package entries.

## Cache Operations

Use generated filters/options for `getQueryData`, `setQueryData`, cancellation,
and invalidation. An optimistic update must define rollback and reconciliation
with the live Convex result. If subscription delivery is fast enough, prefer
pending UI over speculative cache mutation.

## Proof

Test the owner, not TanStack Query itself:

- query is skipped until required identity/input exists;
- mutation pending/error/success states are honest;
- live data changes without a redundant refetch;
- bounded invalidation affects only the intended non-live key;
- RSC hydration and client adoption use one key contract;
- permission failures never render stale privileged data.