Cursor rule

1---
2description: How to use tRPC and react-query in the app
3globs: 
4alwaysApply: false
5---
6The project integrates tRPC with `@tanstack/react-query` by consistently using helper methods provided by the tRPC client. This approach standardizes how queries and mutations are defined and how their respective React Query keys are generated.
7 
8Key characteristics of tRPC usage in this codebase:
9 
101.  **Client Initialization**:
11    *   The tRPC client is obtained within custom React hooks using `const trpc = useTRPC()`. This `useTRPC` hook is typically imported from a central client setup file (e.g., `@/client/trpc`).
12 
132.  **Using `queryOptions` for Queries**:
14    *   When setting up queries with `useQuery` from `@tanstack/react-query`, instead of manually defining query keys and fetcher functions, the code leverages a `queryOptions` helper method available on each tRPC query procedure.
15    *   This method takes the query input as its first argument and an optional object for tRPC/React Query options (like `enabled`) as its second argument.
16    *   Example:
17```typescript
18        // In use-conversation-messages.ts
19        const messagesQuery = useQuery(
20          trpc.message.list.queryOptions(
21            conversationId ? { conversationId } : skipToken,
22            { enabled: queryEnabled },
23          ),
24        );
25 
26        // In use-tenant.ts
27        const { data: tenant } = useQuery(trpc.tenant.getTenant.queryOptions());
28```
29 
303.  **Using `mutationOptions` for Mutations**:
31    *   Similarly, for mutations with `useMutation` from `@tanstack/react-query`, a `mutationOptions` helper method is used. This method is available on each tRPC mutation procedure.
32    *   It can be called without arguments or with an object containing tRPC-specific options. The result is then spread into the `useMutation` hook's options, often alongside React Query mutation callbacks like `onMutate`, `onSuccess`, `onError`, and `onSettled`.
33    *   Example:
34```typescript
35        // In use-chat-assets.ts
36        const createPresignedUrlMutation = useMutation(
37          trpc.asset.generatePresignedUrl.mutationOptions(),
38        );
39 
40        // In use-conversation-delete.ts
41        const mutation = useMutation({
42          ...trpc.conversation.delete.mutationOptions(),
43          onMutate: async (variables) => { /* ... */ },
44          onSuccess: () => { /* ... */ },
45          // ... other callbacks
46        });
47```
48 
494.  **Generating Query Keys with `queryKey`**:
50    *   For operations that require direct interaction with the React Query cache (e.g., invalidating queries, setting query data optimistically), a `queryKey` helper method is used. This method is available on tRPC query procedures and takes the query input as an argument.
51    *   Example:
52```typescript
53        // In use-conversation-messages.ts
54        queryClient.invalidateQueries({
55          queryKey: trpc.conversation.list.queryKey({}),
56        });
57 
58        queryClient.setQueryData(
59          trpc.message.list.queryKey({ conversationId: message.conversationId }),
60          // ... updater function
61        );
62```
63 
645.  **Procedure Path**:
65    *   tRPC procedures are accessed via a path on the initialized `trpc` client object, typically structured as `trpc.namespace.procedureName` (e.g., `trpc.message.list`, `trpc.asset.generatePresignedUrl`).
66 
676.  **Integration with `useQueryClient`**:
68    *   The `useQueryClient` hook from `@tanstack/react-query` is frequently used for cache manipulation tasks like invalidating data, performing optimistic updates, and cancelling outgoing requests, especially within mutation lifecycle callbacks.
69 
70This consistent use of `queryOptions`, `mutationOptions`, and `queryKey` helper methods streamlines the integration with `@tanstack/react-query`, ensuring that query keys are generated correctly and that options are passed in a standardized way. It abstracts away some of the manual setup that might be seen in other tRPC and React Query integrations.
71