Migrate tRPC client to TanStack React Query (#1219)

Co-authored-by: Charles Vien <charles.v@posthog.com>

Author: jonathanlab

apps/code/ARCHITECTURE.md

@@ -14,8 +14,8 @@ Main Process (Node.js)                      Renderer Process (React)
 │  └── ...              │                   │  └── TaskService, ...     │
 ├───────────────────────┤                   ├───────────────────────────┤
 │  tRPC Routers         │ ◄─tRPC(ipcLink)─► │ tRPC Clients              │
-│  (use DI services)    │                   │  ├── trpcReact (hooks)    │
-├───────────────────────┤                   │  └── trpcVanilla          │
+│  (use DI services)    │                   │  ├── useTRPC() (hooks)    │
+├───────────────────────┤                   │  └── trpcClient (vanilla) │
 │  System I/O           │                   ├───────────────────────────┤
 │  (fs, git, shell)     │                   │  Zustand Stores (state)   │
 │  STATELESS            │                   │  ├── taskStore            │
@@ -166,27 +166,84 @@ export const trpcRouter = router({
 
 ### Using tRPC in Renderer
 
-**React hooks:**
+There are three tRPC exports, each for a different context:
+
+| Export | Where to use | Purpose |
+|--------|-------------|---------|
+| `useTRPC()` | React components/hooks | Options proxy via React context |
+| `trpc` | Outside React (module scope, services, stores) | Options proxy bound to the singleton `queryClient` |
+| `trpcClient` | Anywhere (imperative calls) | Vanilla tRPC client for direct `.query()` / `.mutate()` / `.subscribe()` |
+
+**React components** use `useTRPC()` + TanStack Query hooks:
 
 ```typescript
-import { trpcReact } from "@renderer/trpc/client";
+import { useTRPC } from "@renderer/trpc/client";
+import { useMutation, useQuery } from "@tanstack/react-query";
 
 function MyComponent() {
-  // Queries
-  const { data } = trpcReact.my.getData.useQuery({ id: "123" });
-
-  // Mutations
-  const mutation = trpcReact.my.updateData.useMutation();
+  const trpc = useTRPC();
+
+  // Queries — pass queryOptions() to useQuery
+  const { data } = useQuery(
+    trpc.my.getData.queryOptions({ id: "123" }),
+  );
+
+  // Mutations — pass mutationOptions() to useMutation
+  const mutation = useMutation(
+    trpc.my.updateData.mutationOptions({
+      onSuccess: () => { /* ... */ },
+    }),
+  );
   const handleUpdate = () => mutation.mutate({ id: "123", value: "new" });
 }
 ```
 
-**Outside React (vanilla client):**
+**Subscriptions** use `useSubscription` from `@trpc/tanstack-react-query`:
 
 ```typescript
-import { trpcVanilla } from "@renderer/trpc/client";
+import { useSubscription } from "@trpc/tanstack-react-query";
+
+useSubscription(
+  trpc.my.onItemCreated.subscriptionOptions(undefined, {
+    onData: (item) => { /* ... */ },
+  }),
+);
+```
+
+**Cache invalidation** uses `pathFilter()` or `queryFilter()` with the query client:
 
-const data = await trpcVanilla.my.getData.query({ id: "123" });
+```typescript
+const queryClient = useQueryClient();
+
+// Invalidate all queries under a router path
+queryClient.invalidateQueries(trpc.workspace.getAll.pathFilter());
+
+// Invalidate a specific query by input
+queryClient.invalidateQueries(
+  trpc.git.getCurrentBranch.queryFilter({ directoryPath: repoPath }),
+);
+
+// Set cache data directly
+queryClient.setQueryData(
+  trpc.git.getLatestCommit.queryKey({ directoryPath: repoPath }),
+  commitData,
+);
+```
+
+**Outside React** (stores, sagas, services, module-scope utilities):
+
+```typescript
+// Imperative calls — use trpcClient
+import { trpcClient } from "@renderer/trpc/client";
+
+const data = await trpcClient.my.getData.query({ id: "123" });
+await trpcClient.my.updateData.mutate({ id: "123", value: "new" });
+
+// Cache operations outside React — use trpc (the module-level options proxy)
+import { trpc } from "@renderer/trpc";
+import { queryClient } from "@utils/queryClient";
+
+queryClient.invalidateQueries(trpc.workspace.getAll.pathFilter());
 ```
 
 ## State Management
@@ -308,7 +365,7 @@ This pattern provides:
 3. **Register service** in `src/main/di/container.ts`
 4. **Create tRPC router** in `src/main/trpc/routers/`
 5. **Add router** to `src/main/trpc/router.ts`
-6. **Use in renderer** via `trpcReact` hooks
+6. **Use in renderer** via `useTRPC()` + TanStack Query hooks
 
 ## Events (tRPC Subscriptions)
 
@@ -409,25 +466,32 @@ export const shellRouter = router({
 ### 4. Subscribe in Renderer
 
 ```typescript
+import { useSubscription } from "@trpc/tanstack-react-query";
+
+const trpc = useTRPC();
+
 // React component - global events
-trpcReact.my.onItemCreated.useSubscription(undefined, {
-  enabled: true,
-  onData: (item) => {
-    // item is typed as { id: string; name: string }
-    console.log("Created:", item);
-  },
-});
+useSubscription(
+  trpc.my.onItemCreated.subscriptionOptions(undefined, {
+    enabled: true,
+    onData: (item) => {
+      // item is typed as { id: string; name: string }
+    },
+  }),
+);
 
 // React component - per-session events
-trpcReact.shell.onData.useSubscription(
-  { sessionId },
-  {
-    enabled: !!sessionId,
-    onData: (event) => {
-      // event is typed as { sessionId: string; data: string }
-      terminal.write(event.data);
+useSubscription(
+  trpc.shell.onData.subscriptionOptions(
+    { sessionId },
+    {
+      enabled: !!sessionId,
+      onData: (event) => {
+        // event is typed as { sessionId: string; data: string }
+        terminal.write(event.data);
+      },
     },
-  },
+  ),
 );
 ```
 

apps/code/package.json

@@ -132,9 +132,9 @@
     "@tiptap/react": "^3.13.0",
     "@tiptap/starter-kit": "^3.13.0",
     "@tiptap/suggestion": "^3.13.0",
-    "@trpc/client": "^11.8.0",
-    "@trpc/react-query": "^11.8.0",
-    "@trpc/server": "^11.8.0",
+    "@trpc/client": "^11.12.0",
+    "@trpc/server": "^11.12.0",
+    "@trpc/tanstack-react-query": "^11.12.0",
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/addon-serialize": "^0.13.0",
     "@xterm/addon-web-links": "^0.11.0",

apps/code/src/main/services/git/schemas.ts

@@ -128,10 +128,6 @@ export const getDiffStatsOutput = diffStatsSchema;
 export const getCurrentBranchInput = directoryPathInput;
 export const getCurrentBranchOutput = z.string().nullable();
 
-// getDefaultBranch schemas
-export const getDefaultBranchInput = directoryPathInput;
-export const getDefaultBranchOutput = z.string();
-
 // getAllBranches schemas
 export const getAllBranchesInput = directoryPathInput;
 export const getAllBranchesOutput = z.array(z.string());

apps/code/src/main/trpc/routers/git.ts

@@ -29,8 +29,6 @@ import {
   getCommitConventionsOutput,
   getCurrentBranchInput,
   getCurrentBranchOutput,
-  getDefaultBranchInput,
-  getDefaultBranchOutput,
   getDiffStatsInput,
   getDiffStatsOutput,
   getFileAtHeadInput,
@@ -106,11 +104,6 @@ export const gitRouter = router({
     .output(getCurrentBranchOutput)
     .query(({ input }) => getService().getCurrentBranch(input.directoryPath)),
 
-  getDefaultBranch: publicProcedure
-    .input(getDefaultBranchInput)
-    .output(getDefaultBranchOutput)
-    .query(({ input }) => getService().getDefaultBranch(input.directoryPath)),
-
   getAllBranches: publicProcedure
     .input(getAllBranchesInput)
     .output(getAllBranchesOutput)

apps/code/src/renderer/App.tsx

@@ -11,7 +11,9 @@ import { Flex, Spinner, Text } from "@radix-ui/themes";
 import { initializeConnectivityStore } from "@renderer/stores/connectivityStore";
 import { useFocusStore } from "@renderer/stores/focusStore";
 import { useThemeStore } from "@renderer/stores/themeStore";
-import { trpcReact, trpcVanilla } from "@renderer/trpc/client";
+import { trpcClient, useTRPC } from "@renderer/trpc/client";
+import { useQueryClient } from "@tanstack/react-query";
+import { useSubscription } from "@trpc/tanstack-react-query";
 import { initializePostHog } from "@utils/analytics";
 import { logger } from "@utils/logger";
 import { toast } from "@utils/toast";
@@ -22,6 +24,7 @@ import { Toaster } from "sonner";
 const log = logger.scope("app");
 
 function App() {
+  const trpcReact = useTRPC();
   const { isAuthenticated, hasCompletedOnboarding, hasCodeAccess } =
     useAuthStore();
   const isDarkMode = useThemeStore((state) => state.isDarkMode);
@@ -54,48 +57,62 @@ function App() {
 
   // Global workspace error listener for toasts
   useEffect(() => {
-    const subscription = trpcVanilla.workspace.onError.subscribe(undefined, {
+    const subscription = trpcClient.workspace.onError.subscribe(undefined, {
       onData: (data) => {
         toast.error("Workspace error", { description: data.message });
       },
     });
     return () => subscription.unsubscribe();
   }, []);
 
-  const trpcUtils = trpcReact.useUtils();
+  const queryClient = useQueryClient();
 
-  trpcReact.workspace.onPromoted.useSubscription(undefined, {
-    onData: (data) => {
-      void trpcUtils.workspace.getAll.invalidate();
-      toast.info(
-        "Task moved to worktree",
-        `Task is now working in its own worktree on branch "${data.fromBranch}"`,
-      );
-    },
-  });
-
-  trpcReact.workspace.onBranchChanged.useSubscription(undefined, {
-    onData: () => {
-      void trpcUtils.workspace.getAll.invalidate();
-    },
-  });
-
-  trpcReact.focus.onBranchRenamed.useSubscription(undefined, {
-    onData: ({ worktreePath, newBranch }) => {
-      useFocusStore.getState().updateSessionBranch(worktreePath, newBranch);
-      void trpcUtils.workspace.getAll.invalidate();
-    },
-  });
+  useSubscription(
+    trpcReact.workspace.onPromoted.subscriptionOptions(undefined, {
+      onData: (data) => {
+        void queryClient.invalidateQueries(
+          trpcReact.workspace.getAll.pathFilter(),
+        );
+        toast.info(
+          "Task moved to worktree",
+          `Task is now working in its own worktree on branch "${data.fromBranch}"`,
+        );
+      },
+    }),
+  );
+
+  useSubscription(
+    trpcReact.workspace.onBranchChanged.subscriptionOptions(undefined, {
+      onData: () => {
+        void queryClient.invalidateQueries(
+          trpcReact.workspace.getAll.pathFilter(),
+        );
+      },
+    }),
+  );
+
+  useSubscription(
+    trpcReact.focus.onBranchRenamed.subscriptionOptions(undefined, {
+      onData: ({ worktreePath, newBranch }) => {
+        useFocusStore.getState().updateSessionBranch(worktreePath, newBranch);
+        void queryClient.invalidateQueries(
+          trpcReact.workspace.getAll.pathFilter(),
+        );
+      },
+    }),
+  );
 
   // Auto-unfocus when user manually checks out to a different branch
-  trpcReact.focus.onForeignBranchCheckout.useSubscription(undefined, {
-    onData: async ({ focusedBranch, foreignBranch }) => {
-      log.warn(
-        `Foreign branch checkout detected: ${focusedBranch} -> ${foreignBranch}. Auto-unfocusing.`,
-      );
-      await useFocusStore.getState().disableFocus();
-    },
-  });
+  useSubscription(
+    trpcReact.focus.onForeignBranchCheckout.subscriptionOptions(undefined, {
+      onData: async ({ focusedBranch, foreignBranch }) => {
+        log.warn(
+          `Foreign branch checkout detected: ${focusedBranch} -> ${foreignBranch}. Auto-unfocusing.`,
+        );
+        await useFocusStore.getState().disableFocus();
+      },
+    }),
+  );
 
   // Wait for authStore to hydrate, then restore session from stored tokens
   useEffect(() => {