@beignet/react-query 0.0.31 → 0.0.33

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @beignet/react-query
 
+## 0.0.33
+
+### Patch Changes
+
+- c514ffc: Document the Next.js cached request-context convention separately from React
+  Query prefetching, and update generated agent guidance to use
+  `lib/server-context.ts` for shared Server Component request state.
+- ae6d7f9: Document the Next.js server prefetch convention and teach generated agent
+  guidance to preserve contract query keys while replacing server query
+  functions with direct use-case calls.
+
+## 0.0.32
+
 ## 0.0.31
 
 ## 0.0.30

package/README.md

@@ -200,6 +200,33 @@ export async function TodoPage({ params }: { params: { id: string } }) {
 }
 ```
 
+That prefetch path uses the generated HTTP query function. In Next.js apps,
+ordinary `{ contract, useCase }` routes can avoid an internal HTTP request by
+using a cached server-context helper plus a server-only prefetch helper that
+preserves the contract query key and replaces only the server `queryFn`:
+
+```tsx
+import { getTodoUseCase } from "@/features/todos/use-cases";
+import { getAppRequestContext } from "@/lib/server-context";
+import { serverUseCaseQueryOptions } from "@/lib/server-react-query";
+
+const ctx = await getAppRequestContext();
+const queryClient = makeQueryClient();
+
+await queryClient.prefetchQuery(
+  serverUseCaseQueryOptions(
+    rq(getTodo).queryOptions({ path: { id: params.id } }),
+    getTodoUseCase,
+    ctx,
+    { id: params.id },
+  ),
+);
+```
+
+Use the use-case path only when the use case output is the contract success
+body. Use the HTTP `rq(...)` path when the route handler owns response mapping,
+headers, streaming, or other HTTP-layer behavior.
+
 #### Mutation options
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/react-query",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "type": "module",
   "description": "TanStack Query integration for Beignet",
   "main": "./dist/index.js",

package/skills/client/SKILL.md

@@ -97,6 +97,18 @@ Call server behavior through Beignet contracts and typed clients.
 
 - Use `queryOptions(...)` so options work with `useQuery`, `prefetchQuery`,
   `fetchQuery`, and server prefetching.
+- In Next.js Server Components, get Beignet request state from the app's
+  cached server-only context helper (usually `lib/server-context.ts`). Layouts
+  may read `ctx.auth`, `ctx.tenant`, and request metadata from that context;
+  feature data still belongs behind use cases.
+- For React Query hydration, use the app's server-only prefetch helper (usually
+  `lib/server-react-query.ts`) on top of that context for direct
+  `{ contract, useCase }` routes: keep the `rq(contract).queryOptions(...)` key
+  and replace only the server `queryFn` with the use case call. Do not invent a
+  parallel `rqServer` helper.
+- Use HTTP prefetch through `rq(contract).queryOptions(...)` when the route
+  handler owns response mapping, headers, streaming, or other HTTP-layer
+  behavior.
 - Use `mutationOptions(...)` with `useMutation`.
 - Use `infiniteQueryOptions(...)` with `useInfiniteQuery` for paginated
   contracts. Prefer static `path`/`query` plus `page(...)`; if every page needs