or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

hook-creation.mdindex.mdmutation-hooks.mdquery-hooks.mdquery-keys.mdquery-utilities.mdreact-server-components.mdserver-side-helpers.mdsubscription-hooks.md
tile.json

tessl/npm-trpc--react-query

A tRPC wrapper around react-query that provides end-to-end typesafe APIs with React Query integration

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@trpc/react-query@11.5.x

To install, run

npx @tessl/cli install tessl/npm-trpc--react-query@11.5.0

index.mddocs/

tRPC React Query

tRPC React Query is a TypeScript-first React library that provides end-to-end typesafe APIs by integrating tRPC with TanStack React Query. It offers React hooks for queries, mutations, and subscriptions with automatic type inference from tRPC router definitions, built-in caching and background updates, and comprehensive support for server-side rendering.

Package Information

  • Package Name: @trpc/react-query
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @trpc/react-query @tanstack/react-query

Core Imports

Main client-side imports:

import { createTRPCReact } from "@trpc/react-query";
import type { AppRouter } from "./server";

export const trpc = createTRPCReact<AppRouter>();

Server-side helpers:

import { createServerSideHelpers } from "@trpc/react-query/server";

React Server Components (RSC) support:

import { createHydrationHelpers } from "@trpc/react-query/rsc";

Query utilities:

import { getQueryKey, getMutationKey, createTRPCQueryUtils } from "@trpc/react-query";

For CommonJS:

const { createTRPCReact } = require("@trpc/react-query");
const { createServerSideHelpers } = require("@trpc/react-query/server");

Basic Usage

import { createTRPCReact } from "@trpc/react-query";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import type { AppRouter } from "./server";

// Create tRPC React hooks
export const trpc = createTRPCReact<AppRouter>();

// Provider setup
export function App() {
  const [queryClient] = useState(() => new QueryClient());
  const [trpcClient] = useState(() =>
    trpc.createClient({
      url: "http://localhost:5000/trpc",
    })
  );

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

// Component usage
function MyComponent() {
  const { data, error, status } = trpc.greeting.useQuery({ name: "tRPC" });
  const mutation = trpc.updateUser.useMutation();

  if (error) return <p>{error.message}</p>;
  if (status !== "success") return <p>Loading...</p>;

  return <div>{data && <p>{data.greeting}</p>}</div>;
}

Architecture

tRPC React Query is built around several key components:

  • Hook Factory: createTRPCReact generates typed React hooks based on your tRPC router schema
  • Provider System: React context provider that manages client configuration and query client state
  • Procedure Hooks: Dynamically generated hooks (useQuery, useMutation, useSubscription) that mirror your tRPC router structure
  • Utility Functions: Query manipulation utilities available via useUtils() for cache management and imperative operations
  • Type System: Complete TypeScript inference from server router to client hooks with compile-time validation
  • SSR/RSC Support: Server-side helpers for data prefetching and hydration in Next.js and other frameworks

Capabilities

Hook Creation

Core factory function that creates typed React hooks from your tRPC router definition.

function createTRPCReact<TRouter extends AnyRouter, TSSRContext = unknown>(
  opts?: CreateTRPCReactOptions<TRouter>
): CreateTRPCReact<TRouter, TSSRContext>;

interface CreateTRPCReact<TRouter extends AnyRouter, TSSRContext> {
  Provider: TRPCProvider<TRouter, TSSRContext>;
  createClient: typeof createTRPCClient<TRouter>;
  useUtils(): CreateReactUtils<TRouter, TSSRContext>;
  useQueries: TRPCUseQueries<TRouter>;
  useSuspenseQueries: TRPCUseSuspenseQueries<TRouter>;
  // Dynamic router-based hooks are automatically generated
}

Hook Creation

Query Hooks

React hooks for data fetching with caching, background updates, and type safety.

// Generated for each query procedure in your router
procedure.useQuery(input: TInput, opts?: UseTRPCQueryOptions): UseTRPCQueryResult<TData, TError>;
procedure.useSuspenseQuery(input: TInput, opts?: UseTRPCSuspenseQueryOptions): [TData, UseSuspenseQueryResult];
procedure.useInfiniteQuery(input: TInput, opts?: UseTRPCInfiniteQueryOptions): UseTRPCInfiniteQueryResult<TData, TError>;
procedure.useSuspenseInfiniteQuery(input: TInput, opts?: UseTRPCSuspenseInfiniteQueryOptions): [TData, UseSuspenseInfiniteQueryResult];

Query Hooks

Mutation Hooks

React hooks for data modifications with optimistic updates and error handling.

// Generated for each mutation procedure in your router
procedure.useMutation<TContext = unknown>(
  opts?: UseTRPCMutationOptions<TInput, TError, TOutput, TContext>
): UseTRPCMutationResult<TOutput, TError, TInput, TContext>;

Mutation Hooks

Subscription Hooks

React hooks for real-time data subscriptions with automatic connection management.

// Generated for each subscription procedure in your router
procedure.useSubscription(
  input: TInput,
  opts?: UseTRPCSubscriptionOptions<TOutput, TError>
): TRPCSubscriptionResult<TOutput, TError>;

Subscription Hooks

Query Utilities

Comprehensive utility functions for imperative query operations and cache management.

interface CreateReactUtils<TRouter, TSSRContext> {
  // Query manipulation
  invalidate(input?: TInput, opts?: InvalidateOptions): Promise<void>;
  refetch(input?: TInput, opts?: RefetchOptions): Promise<void>;
  cancel(input?: TInput): Promise<void>;
  
  // Data manipulation
  setData(input: TInput, updater: Updater<TData>, opts?: SetDataOptions): void;
  getData(input?: TInput): TData | undefined;
  setInfiniteData(input: TInput, updater: Updater<InfiniteData<TData>>, opts?: SetDataOptions): void;
  getInfiniteData(input?: TInput): InfiniteData<TData> | undefined;
  
  // Imperative fetching
  fetch(input: TInput, opts?: TRPCFetchQueryOptions): Promise<TData>;
  fetchInfinite(input: TInput, opts?: TRPCFetchInfiniteQueryOptions): Promise<InfiniteData<TData>>;
  prefetch(input: TInput, opts?: TRPCFetchQueryOptions): Promise<void>;
  prefetchInfinite(input: TInput, opts?: TRPCFetchInfiniteQueryOptions): Promise<void>;
  ensureData(input: TInput, opts?: TRPCFetchQueryOptions): Promise<TData>;
}

Query Utilities

Server-Side Helpers

Functions for server-side rendering and static generation.

function createServerSideHelpers<TRouter extends AnyRouter>(
  opts: CreateServerSideHelpersOptions<TRouter>
): ServerSideHelpers<TRouter>;

Server-Side Helpers

React Server Components (RSC)

Support for React Server Components with hydration helpers for Next.js App Router and similar frameworks.

function createHydrationHelpers<TRouter extends AnyRouter>(
  caller: Caller<TRouter>,
  getQueryClient: () => QueryClient
): { trpc: DecoratedCaller<TRouter>; HydrateClient: React.ComponentType };

React Server Components

Query Keys and Utilities

Utilities for working with React Query keys and mutations in the tRPC context.

function getQueryKey<TProcedureOrRouter extends ProcedureOrRouter>(
  procedureOrRouter: TProcedureOrRouter,
  ...params: GetParams<TProcedureOrRouter>
): TRPCQueryKey;

function getMutationKey<TProcedure extends DecoratedMutation<any>>(
  procedure: TProcedure
): TRPCMutationKey;

function createTRPCQueryUtils<TRouter extends AnyRouter>(
  opts: CreateQueryUtilsOptions<TRouter>
): TRPCQueryUtils<TRouter>;

Query Keys and Utilities

Types

type CreateTRPCReactOptions<TRouter extends AnyRouter> = {
  context?: React.Context<any>;
  overrides?: {
    useMutation?: {
      onSuccess?: (options: { originalFn: () => void }) => void;
    };
  };
};

type TRPCQueryKey = [
  readonly string[],
  { input?: unknown; type?: Exclude<QueryType, 'any'> }?
];

type TRPCMutationKey = [readonly string[]];

type QueryType = 'any' | 'infinite' | 'query';

interface TRPCReactRequestOptions extends Omit<TRPCRequestOptions, 'signal'> {
  ssr?: boolean;
  abortOnUnmount?: boolean;
}

interface TRPCProvider<TRouter extends AnyRouter, TSSRContext> {
  (props: TRPCProviderProps<TRouter, TSSRContext>): JSX.Element;
}

interface TRPCProviderProps<TRouter extends AnyRouter, TSSRContext> {
  client: TRPCClient<TRouter> | TRPCUntypedClient<TRouter>;
  queryClient: QueryClient;
  ssrContext?: TSSRContext;
  ssrState?: SSRState;
  abortOnUnmount?: boolean;
  children: ReactNode;
}