trpc-uwebsockets

uWebSockets.js adapter for tRPC version 11. Use v10 branch for version 10.

Installation

1npm install trpc-uwebsockets

The versioning of the adapter follows the versioning scheme of trpc. For example, for the @trpc/server version of 11.0.0, the npm package for trpc-uwebsockets will have version 11.0.X, where X is incrementing library version. Ensure that the version of @trpc/server and @trpc/client matches the version of trpc-uwebsockets. Your package manager should provide warnings such as "incorrect peer dependency" if something is wrong.

1npm install uNetworking/uWebSockets.js#v20.51.0

Installation of uWebSockets.js must be done separately, as it is a peer dependency of the project. Version 20.51.0 or higher is required.

Usage

This full example can be found here.

1import * as uWs from 'uWebSockets.js';
2import { initTRPC } from '@trpc/server';
3import z from 'zod';
4
5import {
6  applyRequestHandler,
7  applyWebsocketHandler,
8  CreateContextOptions,
9} from 'trpc-uwebsockets';
10
11/* Define context. During websocket connection do not use `res`, use `client` instead */
12function createContext({ req, res, info, client }: CreateContextOptions) {
13  const user = { name: req.headers.get('username') || 'anonymous' };
14  return { req, res, user, info, client };
15}
16type Context = Awaited<ReturnType<typeof createContext>>;
17
18const t = initTRPC.context<Context>().create();
19
20/* Define app router */
21const appRouter = t.router({
22  hello: t.procedure
23    .input(
24      z
25        .object({
26          username: z.string().nullish(),
27        })
28        .nullish()
29    )
30    .query(
31      ({ input, ctx }) =>
32        `hello ${input?.username ?? ctx.user?.name ?? 'world'}`
33    ),
34  count: t.procedure
35    .input(
36      z
37        .object({
38          from: z.number().positive(),
39          to: z.number().positive(),
40        })
41        .superRefine(({ from, to }, ctx) => {
42          if (to < from) {
43            ctx.addIssue({
44              code: 'custom',
45              message: "'to' must be bigger then 'from'",
46            });
47          }
48        })
49    )
50    .subscription(async function* ({ input, signal }) {
51      for (let i = input.from; i <= input.to; i++) {
52        await new Promise((resolve) => setTimeout(resolve, 20));
53        if (signal?.aborted) {
54          return;
55        }
56        yield i;
57      }
58    }),
59});
60export type AppRouter = typeof appRouter;
61
62/* Create uWebSockets server */
63const app = uWs.App();
64
65/* Handle CORS */
66app.options('/*', (res) => {
67  res.writeHeader('Access-Control-Allow-Origin', '*');
68  res.endWithoutBody();
69});
70
71/* Attach main tRPC event handler */
72applyRequestHandler(app, {
73  prefix: '/trpc',
74  ssl: false /* set to true if your application is served over HTTPS */,
75  trpcOptions: {
76    router: appRouter,
77    createContext,
78    onError(data) {
79      console.error('trpc error:', data);
80    },
81    responseMeta() {
82      return {
83        headers: {
84          'Access-Control-Allow-Origin': '*',
85        },
86      };
87    },
88  },
89});
90
91/* Add websockets support */
92applyWebsocketHandler(app, {
93  prefix: '/trpc',
94  router: appRouter,
95  createContext,
96});
97
98/* Don't crash on undefined requests */
99app.any('/*', (res) => {
100  res.writeStatus('404 NOT FOUND');
101  res.end();
102});
103
104type Server = {
105  stop: () => void;
106  port: number;
107};
108
109async function startServer(port: number): Promise<Server> {
110  return new Promise<Server>((resolve, reject) => {
111    app.listen('0.0.0.0', port, (socket) => {
112      if (socket === false) {
113        return reject(new Error(`Server failed to listen on port ${port}`));
114      }
115      resolve({
116        stop: () => uWs.us_listen_socket_close(socket),
117        port: uWs.us_socket_local_port(socket),
118      });
119    });
120  });
121}

Client example

1import { vi, test, expect, beforeEach, afterEach } from 'vitest';
2
3import {
4  createTRPCClient,
5  createWSClient,
6  splitLink,
7  httpBatchStreamLink,
8  wsLink,
9} from '@trpc/client';
10
11let server: Server;
12
13beforeEach(async () => {
14  // Zero port means that a random port will be used
15  server = await startServer(0);
16});
17afterEach(() => {
18  server.stop();
19});
20
21/* Configure TRPCClient to use WebSockets and BatchStreaming transport */
22function makeClient() {
23  return createTRPCClient<AppRouter>({
24    links: [
25      splitLink({
26        condition(op) {
27          return op.type === 'subscription';
28        },
29        true: wsLink({
30          client: createWSClient({
31            url: `ws://localhost:${server.port}/trpc`,
32          }),
33        }),
34        false: httpBatchStreamLink({
35          url: `http://localhost:${server.port}/trpc`,
36        }),
37      }),
38    ],
39  });
40}
41
42test('query', async () => {
43  const client = makeClient();
44
45  expect(await client.hello.query()).toEqual('hello anonymous');
46  expect(
47    await client.hello.query({
48      username: 'trpc',
49    })
50  ).toEqual('hello trpc');
51});
52
53test('subscription', async () => {
54  const client = makeClient();
55
56  const results: number[] = [];
57  let done = false;
58  client.count.subscribe(
59    { from: 3, to: 7 },
60    {
61      onData(value) {
62        results.push(value);
63      },
64      onStopped() {
65        done = true;
66      },
67    }
68  );
69
70  await vi.waitFor(() => {
71    expect(done).toBe(true);
72  });
73
74  expect(results).toEqual([3, 4, 5, 6, 7]);
75});

Acknowledgements

Big thanks to Ahoy Labs for sponsoring the development of this project!