@beignet/react-query 0.0.55 → 0.0.56

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @beignet/react-query
 
+## 0.0.56
+
+### Patch Changes
+
+- e00c302: Use direct React Query options and declarative invalidation in generated components, with guidance for extracting shared client behavior.
+
 ## 0.0.55
 
 ### Patch Changes

package/README.md

@@ -71,53 +71,57 @@ export function Providers({ children }: { children: ReactNode }) {
 }
 ```
 
-### 3. Add feature client helpers
+### 3. Use contracts in components
 
-Keep root `client/` for shared adapter setup, then put feature-specific query
-options, mutation options, invalidation helpers, and hooks under
-`features/<feature>/client/`:
+Import the app's shared `rq` adapter and browser-safe feature contracts. Pass
+options directly to TanStack Query; `invalidates` selects the queries to refresh
+after a successful mutation:
 
-```ts
-// features/todos/client/queries.ts
-import type { QueryClient } from "@tanstack/react-query";
+```tsx
+"use client";
+
+import { useMutation, useQuery } from "@tanstack/react-query";
 import { rq } from "@/client";
 import { createTodo, listTodos } from "@/features/todos/contracts";
 
-export function listTodosQueryOptions() {
-  return rq(listTodos).queryOptions({ query: {} });
-}
+export function TodoList() {
+  const todos = useQuery(rq(listTodos).queryOptions());
+  const create = useMutation(
+    rq(createTodo).mutationOptions({
+      invalidates: () => [rq(listTodos).contractFilter()],
+    }),
+  );
 
-export function createTodoMutationOptions() {
-  return rq(createTodo).mutationOptions();
-}
+  if (todos.isPending) return <p>Loading todos…</p>;
+  if (todos.isError) return <p role="alert">{todos.error.message}</p>;
 
-export function invalidateTodos(queryClient: QueryClient) {
-  return rq(listTodos).invalidate(queryClient);
+  return (
+    <div>
+      <button
+        type="button"
+        disabled={create.isPending}
+        onClick={() => create.mutate({ body: { title: "New todo" } })}
+      >
+        Add todo
+      </button>
+      {create.isError && <p role="alert">{create.error.message}</p>}
+      <ul>
+        {todos.data.items.map((todo) => <li key={todo.id}>{todo.title}</li>)}
+      </ul>
+    </div>
+  );
 }
 ```
 
-Components can import those helpers and keep UI state separate from cache-key
-construction:
-
-```tsx
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import {
-  createTodoMutationOptions,
-  invalidateTodos,
-  listTodosQueryOptions,
-} from "@/features/todos/client/queries";
-
-function TodoList() {
-  const queryClient = useQueryClient();
-  const todosQuery = useQuery(listTodosQueryOptions());
-  const createTodoMutation = useMutation({
-    ...createTodoMutationOptions(),
-    onSuccess: () => invalidateTodos(queryClient),
-  });
+Pass lifecycle callbacks inside `mutationOptions({ ... })`. Beignet awaits
+`onSuccess`, then the selected invalidations before the mutation settles.
+Declarative invalidation requires TanStack React Query 5.102.0 or newer in v5.
+See [Declarative mutation invalidation](#declarative-mutation-invalidation).
 
-  return <div>{/* ... */}</div>;
-}
-```
+Keep adapter setup in root `client/`. Extract
+[feature client helpers](https://beignetjs.com/react-query#feature-client-helpers)
+for shared query defaults, pagination, optimistic updates, or cache filters used
+by mutations and broadcasts.
 
 ## Usage
 

package/package.json

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

package/skills/client/SKILL.md

@@ -34,39 +34,34 @@ export function makeQueryClient() {
 Reuse the app's existing helper names and client options. Do not introduce a
 parallel Beignet client unless the app already has a multi-client convention.
 
-## Feature Client Helpers
+## Direct Options And Shared Behavior
 
-Feature-specific query options, mutations, and hooks may live under the
-feature. Prefer the canonical directory form for new apps:
+Import contracts, the root `rq` adapter, and TanStack hooks in the component.
+Inside its body, pass options directly to the hooks:
 
-```txt
-features/todos/client/queries.ts
-```
-
-Existing apps may use:
-
-```txt
-features/todos/client.ts
+```ts
+const todos = useQuery(rq(listTodos).queryOptions());
+const create = useMutation(
+  rq(createTodo).mutationOptions({
+    invalidates: () => [rq(listTodos).contractFilter()],
+  }),
+);
 ```
 
-Follow the existing style unless intentionally migrating. Do not mix both
-within one feature.
+Extract feature client modules only when they own reusable behavior: shared
+query defaults, pagination, optimistic updates and rollback, or filters used by
+mutations and broadcasts. Prefer `features/<feature>/client/queries.ts` for
+extracted options. Existing apps may use `features/<feature>/client.ts`; follow
+their style without creating both forms. Keep component callbacks inside
+`mutationOptions({ ... })` so they compose with declarative invalidation.
 
 ```ts
-import type { QueryClient } from "@tanstack/react-query";
+// features/todos/client/queries.ts: a shared freshness default
 import { rq } from "@/client";
-import { createTodo, listTodos } from "@/features/todos/contracts";
+import { listTodos } from "@/features/todos/contracts";
 
 export function listTodosQueryOptions() {
-  return rq(listTodos).queryOptions({ query: { limit: 20 } });
-}
-
-export function createTodoMutationOptions() {
-  return rq(createTodo).mutationOptions();
-}
-
-export function invalidateTodos(queryClient: QueryClient) {
-  return rq(listTodos).invalidate(queryClient);
+  return rq(listTodos).queryOptions({ staleTime: 30_000 });
 }
 ```
 
@@ -160,9 +155,9 @@ If `beignet lint` says a client component reaches a use-case module:
 
 1. Move shared DTOs and validation to `features/<feature>/schemas.ts`.
 2. Remove imports from use cases, routes, infra, providers, or `server/`.
-3. Add a feature client helper that imports only contracts and root client
-   helpers.
-4. Update components to call the helper through TanStack Query.
+3. Import browser-safe contracts and the root `rq` adapter in the component.
+4. Pass `rq(contract).queryOptions()` or `.mutationOptions()` to TanStack Query;
+   extract a feature client helper only for shared behavior.
 
 Then run: