Skip to content
tRPC

WebSocket Link

On this page

wsLink is a terminating link that's used when using tRPC's WebSockets Client and Subscriptions, which you can learn more about here.

Usage

To use wsLink, you need to pass it a TRPCWebSocketClient, which you can create with createWSClient:

client/index.ts
import { function createTRPCClient<TRouter extends AnyRouter>(opts: CreateTRPCClientOptions<TRouter>): TRPCClient<TRouter>createTRPCClient, function createWSClient(opts: WebSocketClientOptions): WsClientcreateWSClient, function wsLink<TRouter extends AnyRouter>(opts: WebSocketLinkOptions<TRouter>): TRPCLink<TRouter>wsLink } from '@trpc/client';
import type { 
type AppRouter = Router<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{}>> & DecorateCreateRouterOptions<{}>
AppRouter
} from './server';
const const wsClient: WsClientwsClient = function createWSClient(opts: WebSocketClientOptions): WsClientcreateWSClient({ UrlOptionsWithConnectionParams.url: CallbackOrValue<string>url: 'ws://localhost:3000', }); const
const trpcClient: TRPCClient<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{}>>>
trpcClient
=
createTRPCClient<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{}>>>(opts: CreateTRPCClientOptions<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{}>>>): TRPCClient<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<...>>>
createTRPCClient
<
type AppRouter = Router<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{}>> & DecorateCreateRouterOptions<{}>
AppRouter
>({
links: TRPCLink<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{}>>>[]
links
: [
wsLink<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{}>>>(opts: WebSocketLinkOptions<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{}>>>): TRPCLink<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{}>>>
wsLink
<
type AppRouter = Router<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{}>> & DecorateCreateRouterOptions<{}>
AppRouter
>({ client: WsClientclient: const wsClient: WsClientwsClient })],
});

Authentication / Connection params

See more here

The wsLink function requires a TRPCWebSocketClient to be passed, which can be configured with the fields defined in WebSocketClientOptions:

export interface WebSocketLinkOptions {
  WebSocketLinkOptions.client: anyclient: type TRPCWebSocketClient = anyTRPCWebSocketClient;
  /**
   * Data transformer
   * @see https://trpc.io/docs/v11/data-transformers
   **/
  WebSocketLinkOptions.transformer?: anytransformer?: type DataTransformerOptions = anyDataTransformerOptions;
}

declare function function createWSClient(opts: WebSocketClientOptions): TRPCWebSocketClientcreateWSClient(opts: WebSocketClientOptionsopts: WebSocketClientOptions): type TRPCWebSocketClient = anyTRPCWebSocketClient;


export interface WebSocketClientOptions {
  /**
   * The URL to connect to (can be a function that returns a URL)
   */
  WebSocketClientOptions.url: string | (() => MaybePromise<string>)url: string | (() => type MaybePromise<T> = T | Promise<T>MaybePromise<string>);
  /**
   * Connection params that are available in `createContext()`
   * These are sent as the first message
   */
  WebSocketClientOptions.connectionParams?: Record<string, string> | (() => MaybePromise<Record<string, string> | null>) | null | undefinedconnectionParams?: type Record<K extends keyof any, T> = { [P in K]: T; }Record<string, string> | null | (() => type MaybePromise<T> = T | Promise<T>MaybePromise<type Record<K extends keyof any, T> = { [P in K]: T; }Record<string, string> | null>);
  /**
   * Ponyfill which WebSocket implementation to use
   */
  
WebSocketClientOptions.WebSocket?: {
    new (url: string | URL, protocols?: string | string[]): WebSocket;
    prototype: WebSocket;
    readonly CONNECTING: 0;
    readonly OPEN: 1;
    readonly CLOSING: 2;
    readonly CLOSED: 3;
} | undefined
WebSocket
?: typeof
var WebSocket: {
    new (url: string | URL, protocols?: string | string[]): WebSocket;
    prototype: WebSocket;
    readonly CONNECTING: 0;
    readonly OPEN: 1;
    readonly CLOSING: 2;
    readonly CLOSED: 3;
}
WebSocket
;
/** * The number of milliseconds before a reconnect is attempted. * @default {@link exponentialBackoff} */ WebSocketClientOptions.retryDelayMs?: ((attemptIndex: number) => number) | undefinedretryDelayMs?: typeof function exponentialBackoff(attemptIndex: number): numberexponentialBackoff; /** * Triggered when a WebSocket connection is established */ WebSocketClientOptions.onOpen?: (() => void) | undefinedonOpen?: () => void; /** * Triggered when a WebSocket connection encounters an error */ WebSocketClientOptions.onError?: ((evt?: Event) => void) | undefinedonError?: (evt: Event | undefinedevt?: Event) => void; /** * Triggered when a WebSocket connection is closed */
WebSocketClientOptions.onClose?: ((cause?: {
    code?: number;
}) => void) | undefined
onClose
?: (
cause: {
    code?: number;
} | undefined
cause
?: { code?: number | undefinedcode?: number }) => void;
/** * Lazy mode will close the WebSocket automatically after a period of inactivity (no messages sent or received and no pending requests) */
WebSocketClientOptions.lazy?: {
    enabled: boolean;
    closeMs: number;
} | undefined
lazy
?: {
/** * Enable lazy mode * @default false */ enabled: booleanenabled: boolean; /** * Close the WebSocket after this many milliseconds * @default 0 */ closeMs: numbercloseMs: number; }; /** * Send ping messages to the server and kill the connection if no pong message is returned */
WebSocketClientOptions.keepAlive?: {
    enabled: boolean;
    intervalMs?: number;
    pongTimeoutMs?: number;
} | undefined
keepAlive
?: {
/** * @default false */ enabled: booleanenabled: boolean; /** * Send a ping message every this many milliseconds * @default 5_000 */ intervalMs?: number | undefinedintervalMs?: number; /** * Close the WebSocket after this many milliseconds if the server does not respond * @default 1_000 */ pongTimeoutMs?: number | undefinedpongTimeoutMs?: number; }; /** * Custom encoder for wire encoding (e.g. custom binary formats) * @default jsonEncoder */ WebSocketClientOptions.experimental_encoder?: anyexperimental_encoder?: type Encoder = anyEncoder; }

Reference

You can check out the source code for this link on GitHub.