React Principles — React Query Hook Scaffold

You scaffold a TanStack Query (React Query) hook following the Server State with React Query recipe.

Step 0 — Load the live recipe (required)

Do this before anything else. The cookbook is the single source of truth and changes over time — never scaffold from memory or from the fallback summary below while the live recipe is reachable.

1. If the reactprinciples MCP server is available, call its get_recipe tool with slug server-state. When the task touches the service/API-client layer, also fetch api-integration.
2. Otherwise fetch: https://www.reactprinciples.dev/cookbook/server-state/llms.txt (and https://www.reactprinciples.dev/cookbook/api-integration/llms.txt when relevant)

The fetched recipe contains the query rules (staleTime, placeholderData, enabled, invalidation) and canonical pattern code for every query type — treat its rules as requirements, not suggestions. If both sources are unreachable (offline), use the fallback summary at the bottom of this file and tell the user you are working from a potentially outdated summary.

When to invoke

• User asks to "create a query hook" or "fetch data from an API"
• User asks for useQuery / useMutation scaffolding
• User mentions TanStack Query, React Query, or server state

Critical check first

Before generating, confirm with the user that this is server state, not client state.

• ✅ Use React Query for: API responses, paginated lists, user data fetched from server, search results
• ❌ Do NOT use React Query for: UI toggles, filter state, theme — use Zustand instead (reactprinciples-store skill)

Inputs needed

Ask the user for:

1. Hook name — camelCase starting with use (e.g., useUsers, useUser, useSearchUsers)
2. Query type — list, detail, debounced search, or mutation
3. Service method — which method on which service (e.g., usersService.getAll, usersService.getById)
4. Query key — which key from queryKeys factory (e.g., queryKeys.users.list(params))
5. Location — src/features/<feature>/hooks/

What to read first

Read existing hooks in the user's project for reference:

src/features/examples/hooks/useUsers.ts       # list with staleTime + placeholderData
src/features/examples/hooks/useUser.ts        # detail with enabled
src/features/examples/hooks/useSearchUsers.ts # debounced search
src/features/examples/hooks/useCreateUser.ts  # mutation with invalidation
src/lib/query-keys.ts                          # query keys factory
src/lib/services/users.ts                      # service layer

Confirm queryKeys has the needed entry — if not, instruct the user to add it.

How to scaffold

Derive the hook from the pattern code for the matching query type in the recipe you fetched in Step 0, wired to the user's service method and query key, and shaped to match the existing hooks you read.

After generating

Tell the user:

1. The file path created
2. Import path: import { use<Resources> } from "@/features/<feature>/hooks/use<Resources>"
3. If queryKeys.<resource> doesn't exist yet, instruct them to add it to src/lib/query-keys.ts
4. If the service method doesn't exist yet, instruct them to add it to the appropriate service file
5. Suggest pairing with HydrationBoundary + dehydrate for SSR prefetch in Next.js page components

What you should NOT do

• Don't use fetch() or axios directly in the hook — call a service method that uses createApiClient
• Don't omit staleTime — explicit is better than relying on defaults
• Don't put the query hook in src/components/ — hooks go in src/features/<x>/hooks/
• Don't mix server state (React Query) and client state (Zustand) in the same hook

Fallback summary (only if Step 0 fails)

May be outdated — the live recipe always wins.

• Always set staleTime explicitly (minutes, not zero); placeholderData: (prev) => prev for paginated lists
• enabled flag for dependent queries (enabled: !!id, enabled: query.length > 0 for search)
• Mutations invalidate the relevant cache: void queryClient.invalidateQueries({ queryKey: ... })
• The chain is service → hook → component; hooks call typed service methods, never fetch directly

Reference

See Server State with React Query recipe and existing hooks in src/features/examples/hooks/.