tRPC React Query Integration

End-to-end type-safe data fetching with

api.xxx.useQuery

,

useMutation

, and cache invalidation via TanStack Query

When to Use

• Fetching data from tRPC procedures in React client components
• Running mutations and automatically invalidating related queries on success
• Optimistically updating the UI before a mutation completes
• Accessing the TanStack Query cache imperatively (prefetch, set data, invalidate)

Instructions

1. Create the typed React hooks

// lib/api.ts (or lib/trpc/client.tsx)
import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '@/server/root';

export const api = createTRPCReact<AppRouter>();

All hooks (

useQuery

useMutation

useSubscription

api.<router>.<procedure>

2. Use useQuery for data fetching

'use client';
import { api } from '@/lib/api';

function PostList() {
  const { data, isLoading, error } = api.post.list.useQuery(
    { limit: 20 },
    {
      staleTime: 60_000,           // Fresh for 60s — won't refetch on mount
      refetchOnWindowFocus: false, // Disable auto-refetch on tab focus
    }
  );

  if (isLoading) return <Skeleton />;
  if (error) return <Error message={error.message} />;

  return <ul>{data.map(post => <li key={post.id}>{post.title}</li>)}</ul>;
}

3. Use useMutation for writes

function CreatePostForm() {
  const utils = api.useUtils();

  const createPost = api.post.create.useMutation({
    onSuccess: (newPost) => {
      // Invalidate and refetch the post list
      void utils.post.list.invalidate();
    },
    onError: (error) => {
      toast.error(error.message);
    },
  });

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      const data = new FormData(e.currentTarget);
      createPost.mutate({
        title: data.get('title') as string,
        content: data.get('content') as string,
      });
    }}>
      <input name="title" />
      <button type="submit" disabled={createPost.isPending}>
        {createPost.isPending ? 'Creating...' : 'Create Post'}
      </button>
    </form>
  );
}

4. Optimistic updates

const utils = api.useUtils();

const likePost = api.post.like.useMutation({
  onMutate: async ({ postId }) => {
    // Cancel outgoing queries for this data
    await utils.post.getById.cancel({ id: postId });

    // Snapshot the current value
    const previous = utils.post.getById.getData({ id: postId });

    // Optimistically update the cache
    utils.post.getById.setData({ id: postId }, (old) =>
      old ? { ...old, likeCount: old.likeCount + 1 } : old
    );

    return { previous };
  },
  onError: (err, { postId }, context) => {
    // Roll back on failure
    if (context?.previous) {
      utils.post.getById.setData({ id: postId }, context.previous);
    }
  },
  onSettled: ({ postId }) => {
    // Always refetch to sync server truth
    void utils.post.getById.invalidate({ id: postId });
  },
});

5. Prefetch data for navigation

// Prefetch on hover for instant page transitions
function PostLink({ postId }: { postId: string }) {
  const utils = api.useUtils();

  return (
    <a
      href={`/posts/${postId}`}
      onMouseEnter={() => {
        void utils.post.getById.prefetch({ id: postId });
      }}
    >
      View Post
    </a>
  );
}

6. Infinite queries for pagination

const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
  api.post.listInfinite.useInfiniteQuery(
    { limit: 20 },
    {
      getNextPageParam: (lastPage) => lastPage.nextCursor,
      initialCursor: undefined,
    }
  );

const allPosts = data?.pages.flatMap((page) => page.items) ?? [];

Details

End-to-end type inference. The

AppRouter

createTRPCReact<AppRouter>()

useQuery

data

useMutation

variables

.input()

api.useUtils()

utils.post.list.invalidate()

utils.post.list.setData()

utils.post.list.prefetch()

queryClient.invalidateQueries

setQueryData

Query key structure. tRPC generates stable query keys from the procedure path and input.

api.post.getById.useQuery({ id: '1' })

api.post.getById.useQuery({ id: '2' })

utils.post.getById.invalidate()

getById

utils.post.getById.invalidate({ id: '1' })

useMutation

mutate

mutateAsync

mutate()

onError

mutateAsync()

await

mutateAsync

Error types.

error

useQuery

useMutation

TRPCClientError<AppRouter>

error.data?.code

error.data?.zodError

error.message

Suspense mode. Replace

useQuery

useSuspenseQuery

data

undefined

Source

https://trpc.io/docs/client/react

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.