Skip to content
Back to skills

Hooks

ASecurity

The React Query hooks forge generates from a service proto — read vs write classification, forge:query-scope, paged use<Rpc>Infinite, and <svc>Queries / <svc>Mutations for reads and writes outside React.

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
developmentreactfrontend

Works with

  • cli

Security analysis

A100/100

Scanned November 18, 2026

npx -y skills add reliant-labs/forge --skill hooks --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Hooks?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Hooks
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-hooks/badge)](https://www.skillsdirectory.com/skills/reliant-labs-hooks)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: proto-hooks
description: The React Query hooks forge generates from a service proto — read vs write classification, forge:query-scope, paged use<Rpc>Infinite, and <svc>Queries / <svc>Mutations for reads and writes outside React.
---

# The generated frontend hooks

`forge generate` writes one hooks file per service (`src/hooks/<svc>-service-hooks_gen.ts`).
Every rpc gets a hook; how it is classified and keyed is decided by the proto.

**Reads get `useQuery`.** An rpc is a read when it declares protobuf's
`option idempotency_level = NO_SIDE_EFFECTS;`, else when its name opens with a
read verb (Get, List, Search, Find, Check, Has, Is, Count, Exists). Declare it
on every read named as a noun (`Health`, `Version`) instead of hand-building
its query key; `IDEMPOTENT` does not make a read. `// forge:mutation` forces a
mutation. Mutation hooks infer `onMutate`'s return as `onError`'s `context`,
so an optimistic rollback needs no cast. A query hook's `select` sets its
`data` type, as in useQuery: `useGetTask(req, { select: toView })` — no
`useMemo` over `data`. A flip leaves the owned starter test's row stale:
`forge generate` prints its line and the new body, and
`forge lint --conventions` fails until it is fixed.

**A mutation hook's `onSuccess` adds to its refresh and never replaces it.**
On success the hook first invalidates its scope (the entity for a CRUD write,
`<svc>Keys.all` otherwise), then calls your `onSuccess`. So a toast or a
redirect cannot leave a list stale. To change the refresh itself, pass
`invalidate`. A function replaces it: `useCreateTask({ invalidate: (qc) => { void
qc.invalidateQueries({ queryKey: taskServiceKeys.listTasks.all }); } })`.
`invalidate: false` skips it. Use that when `onSuccess` writes the response into
the cache with `setQueryData`, or the refetch overwrites what you wrote.

**Scope a custom read with `// forge:query-scope <Entity>`.** A CRUD read is
keyed under its entity, so that entity's CRUD mutations refresh it; a custom
read sits at service scope, which only `<svc>Keys.all` reaches. Above a read
of runs, `// forge:query-scope Run` keys it under `<svc>Keys.run`. Name the
message exactly (a CRUD entity or a message the service declares); it is
declared, not inferred from a `run_id` field, because a filter field is not
what the read reads. Reads only: generate refuses it on a mutation.
`<svc>Keys.<rpc>.all` matches every request of one read, infinite included:
`invalidateQueries({ queryKey: taskServiceKeys.listTasks.all })`. Never test
`queryKey[1]`; a scope moves the method to index 2.

**Paged reads also get `use<Rpc>Infinite`.** A read whose request has a
singular `string page_token` and whose response has `string next_page_token`
(the List shape in `proto`, whatever the rpc is called) gets a useInfiniteQuery
hook too. The shape is the opt-in; there is no marker. It takes the request
minus `pageToken` (the hook owns the token; empty ends the listing), keys
under `<svc>Keys.<rpc>Infinite(req)` within the service and entity scopes so
mutations invalidate it, and `select` reshapes `{ pages }`:
`useListTasksInfinite({ pageSize: 50 }, { select: (d) => d.pages.flatMap((p) => p.tasks) })`.
Never hand-write `useInfiniteQuery` over a generated key.

**Outside React, use `<svc>Queries`.** Each read's TanStack options:
`<svc>Queries.<rpc>(req, options?)` is `queryOptions`, `.<rpc>Infinite(req)`
`infiniteQueryOptions`; the hooks are built over them, so they share one cache
entry and fetch. `await queryClient.fetchQuery(taskServiceQueries.getTask({ id }))`
(also `ensureQueryData`, `prefetchQuery`, `fetchInfiniteQuery`,
`useQueries({ queries })`), typed with no annotation. Never hand-write
`{ queryKey, queryFn }` for a generated rpc.

**Writes outside React use `<svc>Mutations`.** A store, sync service or OAuth
callback calls `await taskServiceMutations(queryClient).createTask(req, { signal })`:
the rpc, then on success the same invalidation `useCreateTask` does (entity
scope for CRUD, `<svc>Keys.all` otherwise). It resolves with the response,
rejects with a `ConnectClientError`, and bypasses the MutationCache, so no
error toast fires. Never hand-write a client call plus `invalidateQueries`.

When the app must preserve a narrower success refresh than the generated key,
pass `{ invalidate: (qc) => { void invalidateWorktreeQueries(qc, worktreeId); } }`
as the write's second argument. This **replaces**, not adds to, the generated
invalidation for that call only; omitted keeps the old default. It runs only
after RPC success and is not awaited (like the default refetch). Handle async
failures inside it; a synchronous throw rejects after the server has already
written, without rollback or retry. Keep non-cache product effects outside it.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.