React Query Integration and Inferred Hooks
What you'll learn: How tRPC automatically generates fully-typed useQuery and useMutation hooks through its @trpc/react-query integration, eliminating manual type annotations.
The Integration Magic
Once you've defined your tRPC router on the backend, the @trpc/react-query package creates React hooks that know the exact input and output types for every procedure. You don't write type annotations—tRPC infers them from your router definition.
This integration leverages React Query's powerful data-fetching primitives while adding end-to-end type safety. The hooks you call on the frontend are generated from the same AppRouter type you've been using.
The Setup Pattern
Your frontend client typically exposes these hooks through a utility function that wraps your router type:
// On frontend: utils/trpc.ts
import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '../server/router'; // Your backend router type
export const trpc = createTRPCReact<AppRouter>();
Notice the generic <AppRouter> type parameter—this is where all the type inference originates.
Using Inferred Query Hooks
When you call a query procedure, the hook automatically knows what input it expects and what data it returns:
function UserProfile() {
// TypeScript knows this query expects { userId: string }
// and returns a User object (from your backend schema)
const { data, isLoading } = trpc.user.getById.useQuery({
userId: "123"
});
if (isLoading) return <div>Loading...</div>;
// data is fully typed as User | undefined
return <div>{data?.name}</div>;
}
The useQuery hook is not a generic you manually type—it's a property on your trpc client that already has the right type baked in.
Using Inferred Mutation Hooks
Mutations work identically, with full inference of input and output:
function CreatePostForm() {
const mutation = trpc.post.create.useMutation();
const handleSubmit = (title: string, content: string) => {
// TypeScript knows mutate() expects { title: string; content: string }
mutation.mutate({ title, content }, {
onSuccess: (createdPost) => {
// createdPost is typed as Post (your backend return type)
console.log(`Created post with ID: ${createdPost.id}`);
}
});
};
return <form>{ /* form fields */ }</form>;
}
All the React Query features—caching, refetching, optimistic updates—work as expected, but with complete type safety.
Why This Matters
Without this integration, you'd manually write hooks, type their inputs and outputs, and hope the backend didn't change. With @trpc/react-query, your router definition is the single source of truth. Change a procedure's input schema, and every frontend call immediately shows a type error if it doesn't match.
Key Takeaway: @trpc/react-query transforms your backend router into type-safe React hooks automatically—no manual typing, no code generation, just inferred types flowing from server to client through your AppRouter type.