# Tanstack Query

> Use for TanStack Query v5 server-state code: keys, options, freshness, mutations, invalidation, optimistic updates, pagination, cancellation, or SSR. Not for generic React state, performance, routers, or backend caches.

- **Type:** Skill
- **Install:** `agentstack add skill-mblauberg-provenant-tanstack-query`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mblauberg](https://agentstack.voostack.com/s/mblauberg)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mblauberg](https://github.com/mblauberg)
- **Source:** https://github.com/mblauberg/provenant/tree/main/skills/tanstack-query

## Install

```sh
agentstack add skill-mblauberg-provenant-tanstack-query
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# TanStack Query

Design TanStack Query as a server-state boundary, not a fetch-hook convenience.
This skill targets `@tanstack/react-query` v5. Confirm the installed major and
framework adapter before changing APIs; use current official documentation for
version-sensitive behaviour.

## Core rules

- Query keys are top-level arrays, JSON-serialisable and complete: include every
  input that can change the returned data. Centralise families without hiding
  their hierarchy.
- Co-locate `queryKey` and `queryFn` with `queryOptions`; reuse that contract for
  hooks, prefetching, invalidation and cache updates.
- Query functions throw/reject on failure and consume the supplied `AbortSignal`
  when the transport supports cancellation.
- Choose `staleTime` from data semantics. Choose `gcTime` from inactive-cache
  retention needs. Do not suppress focus/reconnect refetches to conceal a poor
  freshness policy.
- Prefer targeted invalidation after mutations. Use `setQueryData` only when the
  response is canonical for the exact cached shape.
- Optimistic UI through mutation variables is simpler than cache mutation. If
  updating the cache, cancel matching queries, snapshot, update immutably,
  restore on error and invalidate on settlement.
- Keep initial loading, background fetching, empty data and errors distinct.
  Never blank usable data merely because `isFetching` is true.
- Avoid serial request waterfalls: start independent queries together and
  prefetch at route or intent boundaries where evidence justifies it.
- Create a request-scoped `QueryClient` for SSR. Never share a server cache
  between users. Hydrate only serialisable, authorised data.
- Tests receive a fresh `QueryClient`, disabled retries for error cases and
  network behaviour exercised at the public boundary.

## Workflow

1. Inventory query clients, key families, option factories, mutation effects,
   SSR boundaries and existing tests.
2. State freshness, invalidation, concurrency and error invariants before code.
3. Implement through `tdd`; load `typescript-clean-code` for type boundaries and
   `react-performance` only for broader React/Next.js performance.
4. Run tests, typecheck and the TanStack Query ESLint plugin where installed.
5. Review with [review-checklist.md](references/review-checklist.md).

Load [patterns.md](references/patterns.md) for implementation patterns and
[sources.md](references/sources.md) for the official source map and provenance.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mblauberg](https://github.com/mblauberg)
- **Source:** [mblauberg/provenant](https://github.com/mblauberg/provenant)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mblauberg-provenant-tanstack-query
- Seller: https://agentstack.voostack.com/s/mblauberg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.