tRPC Subscriptions
The tRPC socket adapters connect a HyperFetch
Socketto tRPC subscriptions, over WebSocket or Server-Sent Events. Subscription procedures become typed listeners, with the procedure input as the payload.
- Listen to tRPC subscriptions with the
Socket,ListeneranduseListenerAPI you use for other realtime sources. - Infer types from your router with
TrpcSocketSchemaandcreateSocketSdk. - Share one server subscription between every listener with the same input.
- Resume after reconnecting from the last
tracked()event. - Support transformers such as
superjson.
Installation
The socket adapters live in the tRPC package and need @hyper-fetch/sockets.
npm install @hyper-fetch/core @hyper-fetch/sockets @hyper-fetch/trpc
WebSocket
TrpcWebsocketAdapter speaks the protocol of wsLink, so it works with applyWSSHandler from
@trpc/server/adapters/ws.
import { initTRPC, tracked } from "@trpc/server";
import { applyWSSHandler } from "@trpc/server/adapters/ws";
import { WebSocketServer } from "ws";
const t = initTRPC.create();
export const appRouter = t.router({
chat: t.router({
onMessage: t.procedure
.input((value) => value as { room: string; lastEventId?: string })
.subscription(async function* ({ input, signal }) {
for await (const message of messages(input.room, { after: input.lastEventId, signal })) {
yield tracked(message.id, message);
}
}),
}),
});
export type AppRouter = typeof appRouter;
applyWSSHandler({ wss: new WebSocketServer({ port: 3001 }), router: appRouter });
Create a socket with the adapter and describe the router with TrpcSocketSchema.
import { Socket, createSocketSdk } from "@hyper-fetch/sockets";
import { TrpcWebsocketAdapter } from "@hyper-fetch/trpc";
import type { TrpcSocketSchema } from "@hyper-fetch/trpc";
import type { AppRouter } from "./server";
export const socket = new Socket({ url: "ws://localhost:3001", adapter: TrpcWebsocketAdapter() });
export const realtime = createSocketSdk<typeof socket, TrpcSocketSchema<AppRouter>>(socket, {
camelCaseToKebabCase: false,
});
const stop = realtime.chat.onMessage.$listener.setPayload({ room: "general" }).listen(({ data, extra }) => {
console.log(data.text, extra.eventId);
});
Every subscription procedure becomes a $listener. Its topic is the procedure path with slashes (chat/onMessage), and
queries and mutations are left out of the schema - send them with the
TrpcAdapter.
Server-Sent Events
TrpcSseAdapter speaks the protocol of httpSubscriptionLink, so it works with the HTTP handlers of tRPC
(createHTTPServer, fetchRequestHandler and the other adapters). Point the socket at the URL of the HTTP handler.
import { Socket } from "@hyper-fetch/sockets";
import { TrpcSseAdapter } from "@hyper-fetch/trpc";
export const socket = new Socket({ url: "http://localhost:3000/trpc", adapter: TrpcSseAdapter() });
Every subscription gets its own EventSource, opened as GET {url}/chat.onMessage?input={"room":"general"}. The socket
counts as connected once it can open the streams, and socket.disconnect() closes all of them.
- WebSocket keeps one connection for every subscription. Use it when a client holds many subscriptions at once.
- Server-Sent Events need no WebSocket server and pass through HTTP proxies and serverless platforms. Use them when you already serve tRPC over HTTP.
- Both adapters share the schema, the payloads and the
extra, so switching only changes the socket.
Both adapters use the global WebSocket and EventSource. In environments without them, such as EventSource in
Node.js, pass the class in the adapterOptions.
import { EventSource } from "eventsource";
const socket = new Socket({
url: "http://localhost:3000/trpc",
adapter: TrpcSseAdapter(),
adapterOptions: { EventSource },
});
The WebSocket adapter takes WebSocket the same way, for example from the ws package.
Inputs and shared subscriptions
The procedure input is the listener payload. Set it with setPayload() or pass it to listen().
realtime.chat.onMessage.$listener.setPayload({ room: "general" }).listen(onMessage);
realtime.chat.onMessage.$listener.listen(onMessage, { payload: { room: "general" } });
The payload follows the procedure: it is required when the input is required, optional when the input is optional, and not taken when the procedure has no input.
- Listeners with the same input share one server subscription. The first one starts it and the last one to leave stops
it (
subscription.stopover WebSocket, closing the stream over SSE). - Listeners with different inputs are separate subscriptions and never receive each other's events.
- Listeners created before the socket connects wait, and their subscriptions start when it connects.
Tracked events and resuming
Events yielded with tracked(id, data) reach the listeners as data, without the wrapper. The id is in the extra.
realtime.chat.onMessage.$listener.setPayload({ room: "general" }).listen(({ data, extra }) => {
data; // { id: string; room: string; text: string }
extra.eventId; // "message-42", or null for events that are not tracked
extra.payload; // { room: "general" }
});
After a reconnect, every subscription is restarted with the last event id as lastEventId, and tRPC passes it to the
procedure in input.lastEventId. A procedure that reads it can send the events the client missed. Over SSE the
EventSource also sends it as Last-Event-ID when it reconnects on its own.
React
useListener from @hyper-fetch/react works with both adapters. Changing the payload stops the previous subscription
and starts a new one, and unmounting stops it.
import { useListener } from "@hyper-fetch/react";
const ChatRoom = ({ room }: { room: string }) => {
const { data, extra, connected } = useListener(realtime.chat.onMessage.$listener.setPayload({ room }));
return (
<div>
<p>{connected ? "Live" : "Connecting..."}</p>
<p>{data?.text}</p>
<span>{extra?.eventId}</span>
</div>
);
};
Errors
Subscription errors are reported to the socket.onError callbacks as a TrpcSocketError. Its shape holds the error
sent by the server, after the transformer, and topic and payload tell which subscription failed.
import { TrpcSocketError } from "@hyper-fetch/trpc";
socket.onError(({ error }) => {
if (error instanceof TrpcSocketError) {
error.topic; // "chat/onMessage", or null when the server rejected the whole connection
error.payload; // { room: "general" }
error.shape.data.code; // "UNAUTHORIZED"
}
});
- Over WebSocket, an error ends the subscription on the server.
- Over SSE, errors with the
INTERNAL_SERVER_ERRORcode keep the stream, and theEventSourcereconnects. Other errors end the subscription, the same wayhttpSubscriptionLinkhandles them. - Messages that don't follow the protocol, and callbacks that throw, are reported to
onErrortoo. The connection stays open and the other listeners keep receiving events.
Subscription lifecycle
The server confirms every subscription and tells when it is over, so listen() takes onStart and onEnd.
realtime.chat.onMessage.$listener.setPayload({ room: "general" }).listen(onMessage, {
onStart: ({ topic }) => {
// The server accepted the subscription, and again after every reconnect
},
onEnd: ({ topic, error }) => {
// The procedure returned (`error` is null) or failed with a TrpcSocketError
},
});
| Event | WebSocket | Server-Sent Events |
|---|---|---|
onStart | started result | connected event of the stream |
onEnd, no error | stopped result | return event |
onEnd, with error | error of the subscription | serialized-error that is not retryable, failed stream |
- A listener that joins a subscription the server already confirmed gets
onStartright away. - After a reconnect, or when the
EventSourcereconnects on its own,onStartruns again once the server confirms the restarted subscription. - On the end, events still pending in a
deliverystrategy are delivered first. Then the listener unsubscribes andonEndruns. Errors also reachsocket.onError. - An ended subscription is never restarted by a reconnect. A new
listen()with the same input starts a fresh one, without the last event id of the old one. - Errors of the whole connection, such as a failing
createContext, are reported tosocket.onErrorand don't end the subscriptions. - Unsubscribing yourself does not call
onEnd.
useListener follows the same lifecycle in status: "idle", "starting" until the server confirms, "listening",
then "ended" or "failed" with the error. Call listen() from the hook to subscribe again.
const { data, status, error, listen } = useListener(realtime.onCount.$listener.setPayload({ to: 10 }));
if (status === "failed") {
return <p>{error?.message}</p>;
}
Connection params
Pass connectionParams in the adapterOptions to send values that the server reads in createContext as
info.connectionParams. The WebSocket adapter sends them as the first message of every connection, the SSE adapter adds
them to the URL of every stream.
const socket = new Socket({
url: "ws://localhost:3001",
adapter: TrpcWebsocketAdapter(),
adapterOptions: { connectionParams: { token: getToken() } },
});
To resolve a fresh value for every connection attempt, for example a short-lived token, change it in socket.onConnect.
socket.onConnect(async ({ connection }) => ({
...connection,
adapterOptions: { ...connection.adapterOptions, connectionParams: { token: await refreshToken() } },
}));
Keep-alive
The WebSocket adapter answers the PING of the server. Enable keepAlive to send its own PING on a quiet connection
and reconnect when the PONG does not arrive in time.
const socket = new Socket({
url: "ws://localhost:3001",
adapter: TrpcWebsocketAdapter(),
adapterOptions: { keepAlive: { enabled: true, intervalMs: 5000, pongTimeoutMs: 1000 } },
});
Over SSE the server decides. When it sets sse.client.reconnectAfterInactivityMs in initTRPC.create(), a stream that
gets no event or ping for that long is restarted from the last event.
Timeouts and cleanup
The socket options control the timing, the same way as for every socket adapter (see retries).
connectionTimeout(5 seconds by default) limits one connection attempt: the WebSocket handshake, or a stream that has not received theconnectedevent yet, also while theEventSourceretries it on its own. An attempt that takes longer is a failed attempt, and the next one follows the reconnection delay.reconnectTime(1 second by default) andmaxReconnectTime(30 seconds by default) bound the delay before the WebSocket adapter connects again after the connection was lost. The delay grows with every failed attempt, with jitter, and resets once a connection stays up forminUptime.- When the server asks the client to reconnect, the adapter moves to a new connection right away - also after the
reconnectattempts ran out.
const socket = new Socket({
url: "ws://localhost:3001",
adapter: TrpcWebsocketAdapter(),
connectionTimeout: 10_000,
reconnectTime: 500,
maxReconnectTime: 10_000,
});
Call socket.destroy() when the socket is not needed anymore. It closes the connection and stops following the online
state of the app, so a destroyed socket never connects again.
Transformers
Pass the same transformer that the server uses in initTRPC.create(). It handles the inputs, the events and the errors.
import superjson from "superjson";
const socket = new Socket({ url: "ws://localhost:3001", adapter: TrpcWebsocketAdapter({ transformer: superjson }) });
realtime.event.onCreated.$listener.listen(({ data }) => {
data.createdAt; // Date
});
Limitations
- The socket adapters handle subscriptions only.
emitter.emit()throws, send queries and mutations with theTrpcAdapter. - WebSocket batching, lazy connections and custom encoders (
experimental_encoder) are not supported. - A procedure that yields its own
{ id, data }objects withouttracked()is typed as tracked. Wrap the events withtracked()or use other field names.
TrpcWebsocketAdapterandTrpcSseAdapterconnect aSocketto tRPC subscriptions over WebSocket or SSE.TrpcSocketSchemamaps the subscriptions of a router to$listeners with typed payloads and events.- Listeners with the same input share one server subscription, different inputs never mix.
extra.eventIdholds the id of tracked events, and subscriptions resume from it after reconnecting.onStartandonEnd(andstatusinuseListener) follow the server - an ended subscription takes a newlisten().- Errors arrive in
socket.onErroras aTrpcSocketError.

