@bunnyapp/components 1.6.0-beta.14 → 1.6.0-beta.16

package/README.md

@@ -104,6 +104,48 @@ npm run codegen
 npx gql-tada doctor
 ```
 
+### Development best practices
+
+**Updating the React Query cache with typed data**
+
+Sometimes you want to update the React Query cache directly instead of running another query.  
+To keep this safe, you should make sure the data you write into the cache is **strongly typed** and matches what your components expect.  
+One simple pattern is to create small hooks that accept a GraphQL fragment, and use that fragment to type the data you store in the cache.
+
+Below is a minimal, generic example using a `FruitFragment` and a `useSetFruitQueryData` hook:
+
+```typescript
+const FruitFragment = graphql(`
+  fragment FruitFragment on Fruit {
+    id
+    name
+  }
+`);
+
+export const useSetFruitQueryData = () => {
+  const queryClient = useQueryClient();
+
+  const setFruitQueryData = (
+    fruitId: string,
+    maskedFruit: FragmentOf<typeof FruitFragment> | null
+  ) => {
+    queryClient.setQueryData(['fruit', fruitId], maskedFruit);
+  };
+
+  return { setFruitQueryData };
+};
+```
+
+Using this hook, the data you write to the cache is constrained by the `FragmentOf<typeof FruitFragment>` type:
+
+```typescript
+const { setFruitQueryData } = useSetFruitQueryData();
+
+setFruitQueryData('123', { id: '123', name: 'Apple' });
+```
+
+For a more complete example in the codebase, see the `useSetQuoteQueryData` hook in the `quantityChangeDrawer` module.
+
 ### Deprecating @bunnyapp/common
 
 We are gradually deprecating `@bunnyapp/common` and moving types and enums locally to this repository. When something is moved from `@bunnyapp/common`, follow this pattern: