The Complete Production SOP: How to Deploy and Run tRPC React Query Client Integration & Optimistic Hooks in Autonomous AI Agents

---
name: "trpc-query-react-client-binding"
description: "Consume tRPC endpoints in React components with TanStack Query hooks and full autocomplete."
metadata:
  author: "tRPC"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "setup trpc react client"
  - "trpc.usequery react"
  - "invalidate trpc cache useutils"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '@/server/routers/_app';

// Deterministic type-safe hook bindings
export const trpc = createTRPCReact<AppRouter>();

'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { httpBatchLink } from '@trpc/client';
import React, { useState } from 'react';
import superjson from 'superjson';
import { trpc } from '@/utils/trpc';

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 5 * 1000,
        refetchOnWindowFocus: false,
      },
    },
  }));

  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [
        httpBatchLink({
          url: '/api/trpc',
          transformer: superjson,
          headers: () => ({
            'x-client-platform': 'web',
          }),
        }),
      ],
    })
  );

  return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </trpc.Provider>
  );
}

'use client';

import { trpc } from '@/utils/trpc';

export function TaskToggle({ taskId, completed }: { taskId: string; completed: boolean }) {
  const utils = trpc.useUtils();

  const mutation = trpc.tasks.toggle.useMutation({
    onMutate: async (variables) => {
      // Cancel outgoing refetches so they don't overwrite optimistic update
      await utils.tasks.list.cancel();
      const prevData = utils.tasks.list.getData();

      // Optimistically update cache
      utils.tasks.list.setData(undefined, (old) =>
        old?.map((task) =>
          task.id === variables.id ? { ...task, completed: variables.completed } : task
        )
      );
      return { prevData };
    },
    onError: (err, variables, context) => {
      // Rollback to previous state on failure
      if (context?.prevData) {
        utils.tasks.list.setData(undefined, context.prevData);
      }
    },
    onSettled: () => {
      // Always sync cache with server truth
      utils.tasks.list.invalidate();
    },
  });

  return (
    <button
      onClick={() => mutation.mutate({ id: taskId, completed: !completed })}
      disabled={mutation.isPending}
    >
      {completed ? 'Mark Incomplete' : 'Mark Complete'}
    </button>
  );
}