# Reactprinciples Query

> Scaffold a TanStack Query hook following React Principles server-state recipe — staleTime, placeholderData, enabled, queryKeys factory.

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

---


# React Principles — React Query Hook Scaffold

You scaffold a TanStack Query (React Query) hook following the [Server State with React Query](https://www.reactprinciples.dev/cookbook/server-state) 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

## Adapt to the existing repo

Match the conventions already in this project. Where the project's query style differs from the cookbook pattern, follow the project and note the difference once — do not force the cookbook approach.

Non-negotiable (correctness, not taste): server state goes in React Query, never in Zustand; staleTime must be explicit; hooks call typed service methods, never `fetch` directly.

## 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)

⚠️ Working from offline summary — live recipe may be more current.

- 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](https://www.reactprinciples.dev/cookbook/server-state) and existing hooks in `src/features/examples/hooks/`.