Skip to main content
Version: v9.0.0

tRPC Adapter

Read the API Reference »

The Hyper Fetch tRPC Adapter connects Hyper Fetch to a tRPC server, so procedures get caching, queueing, offline support and React hooks, with types inferred from your router.

Purpose
  1. Call tRPC procedures with the same request API you use for REST and GraphQL.
  2. Infer types from your router through the regular createSdk.
  3. Cache every input separately, without writing query keys by hand.
  4. Support transformers such as superjson.

Installation​

Install the adapter next to the core package. @trpc/server is only needed for the TrpcSchema type, and your project that imports the AppRouter type usually has it already.

npm install @hyper-fetch/core @hyper-fetch/trpc

Getting Started​

Point the client at the URL where your tRPC handler is mounted, and describe the router with TrpcSchema.

import { createClient, createSdk } from "@hyper-fetch/core";
import { TrpcAdapter } from "@hyper-fetch/trpc";
import type { TrpcSchema } from "@hyper-fetch/trpc";

import type { AppRouter } from "./server";

const client = createClient({ url: "http://localhost:3000/trpc" }).setAdapter(TrpcAdapter());

const api = createSdk<typeof client, TrpcSchema<AppRouter>>(client, { camelCaseToKebabCase: false });

const { data, error } = await api.user.byId.$query.setPayload({ id: 1 }).send();

camelCaseToKebabCase: false keeps procedure names as they are written in the router (byId, not by-id).


Queries​

Queries are available under $query. The procedure input is the request payload.

import { useFetch } from "@hyper-fetch/react";

const { data, loading } = useFetch(api.user.byId.$query.setPayload({ id: 1 }));

They are sent as GET {url}/user.byId?input={"id":1}, with the input URL-encoded. Like GET requests in the HttpAdapter, identical queries running at the same time are deduplicated by default.


Mutations​

Mutations are available under $mutation and are sent as POST {url}/user.create with a JSON body.

import { useSubmit } from "@hyper-fetch/react";

const { submit } = useSubmit(api.user.create.$mutation);

await submit({ payload: { name: "John" } });

Requests without the SDK​

The SDK is optional. QUERY and MUTATION are the methods of this adapter, and the endpoint is the procedure path.

const getUser = client.createRequest<{ response: User; payload: { id: number } }>()({
endpoint: "user.byId",
method: "QUERY",
});

const createUser = client.createRequest<{ response: User; payload: { name: string } }>()({
endpoint: "user.create",
method: "MUTATION",
});

QUERY is the default method. The paths user.byId and /user/byId point to the same procedure and share the cache.


Cache keys​

The adapter adds the input to the cache and query keys, so { id: 1 } and { id: 2 } are cached, deduplicated and queued separately. The abort key does not contain the input, so request.abort() stops every running call of the procedure.

A cancelable request replaces the running call with the same query key, which means the same input. To cancel the previous call when the input changes, for example in a search field, share the query key between the inputs.

const search = api.user.search.$query.setCancelable(true).setDeduplicate(false).setQueryKey("user-search");

Errors​

Failed procedures resolve with the error sent by the server and the HTTP status of the response.

const { error, status, extra } = await api.user.byId.$query.setPayload({ id: 999 }).send();

status; // 404
error?.message; // "User not found"
error?.code; // -32004
error?.data.code; // "NOT_FOUND"
error?.data.httpStatus; // 404
extra?.headers; // response headers

With TrpcSchema the error type follows the router, including a custom errorFormatter. For requests created by hand, use the exported TrpcErrorType.

A response that did not come from a procedure, such as an HTML error page from a proxy, resolves with an UnexpectedError and the status of that response.


Transformers​

Pass the same transformer that the server uses in initTRPC.create(). It handles the input, the output and the errors.

import superjson from "superjson";

const client = createClient({ url: "http://localhost:3000/trpc" }).setAdapter(
TrpcAdapter({ transformer: superjson }),
);

const { data } = await api.event.byDate.$query.setPayload({ date: new Date() }).send();

data?.createdAt; // Date

Any object with serialize and deserialize methods works. When the server uses separate transformers for each direction, pass { serialize: input.serialize, deserialize: output.deserialize }.


Options​

Request options are passed to fetch, with an additional timeout in milliseconds (5 seconds by default).

const getUser = client.createRequest<{ response: User }>()({
endpoint: "user.me",
options: { credentials: "include", timeout: 10000 },
});

Query params are appended to the URL. The input and batch keys are reserved for the tRPC format and are skipped.


Limitations​

  • Subscriptions and request batching are not supported. Subscription procedures are left out of TrpcSchema.
  • A null payload removes the payload, so the procedure receives no input. Procedures that need a null input should take an object instead, for example { value: null }.
  • The SDK can't reach a procedure named like a request property, such as send or method. Use createRequest with the procedure path for those.