# Tanstack Query

> Convert a page or component from useAsyncData/manual ref patterns to TanStack Query for server state management. Use when migrating data fetching to useQuery/useMutation, adding cache invalidation, or replacing useAsyncData with TanStack Query.

- Skill: `mystic-stars/tanstack-query` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mystic-stars/tanstack-query`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mystic-stars/tanstack-query/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: mystic-stars (https://skillmd.com/u/mystic-stars)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mystic-stars/tanstack-query

---


## Steps

1. **Read the target file** at `$ARGUMENTS` and identify all data-fetching patterns: `useAsyncData`, `useFetch`, manual `ref()` + `await`, or `onMounted` fetch calls.
2. **Define query boundaries**: use stable hierarchical keys, preserve reactive parameters, and decide whether mutation feedback needs an optimistic update.
3. **Convert queries:**
   - Replace `useAsyncData` / `useFetch` / manual fetches with `useQuery`.
   - Use the `api-client` via `injectModrinthClient()` for the `queryFn`.
   - Design query keys with the `['resource', 'version', ...params]` convention.
   - Use `computed` query keys for reactive parameters.
   - Use the `enabled` option for conditional queries that depend on other data.
4. **Convert mutations:**
   - Replace manual `try/catch` + `ref` patterns with `useMutation`.
   - Add `onSuccess` handlers that invalidate or update related query caches.
   - Consider optimistic updates for UI-critical mutations.
5. **Clean up:**
   - Remove manual loading/error `ref()`s that are now handled by TanStack Query's return values (`isPending`, `isError`, `error`).
   - Remove manual `onMounted` fetch calls.
   - Preserve the target surface's lifecycle behavior and avoid introducing duplicate initial requests.
6. **Verify** the page still renders correctly and that cache invalidation triggers re-fetches where expected.