tRPC — Adapter: Fastify

Setup

// server.ts
import { initTRPC } from '@trpc/server';
import {
  fastifyTRPCPlugin,
  FastifyTRPCPluginOptions,
} from '@trpc/server/adapters/fastify';
import type { CreateFastifyContextOptions } from '@trpc/server/adapters/fastify';
import fastify from 'fastify';
import { z } from 'zod';

function createContext({ req, res }: CreateFastifyContextOptions) {
  return { req, res };
}
type Context = Awaited<ReturnType<typeof createContext>>;

const t = initTRPC.context<Context>().create();

const appRouter = t.router({
  greet: t.procedure
    .input(z.object({ name: z.string() }))
    .query(({ input }) => ({ greeting: `Hello, ${input.name}!` })),
});

export type AppRouter = typeof appRouter;

const server = fastify({
  routerOptions: {
    maxParamLength: 5000,
  },
});

server.register(fastifyTRPCPlugin, {
  prefix: '/trpc',
  trpcOptions: {
    router: appRouter,
    createContext,
    onError({ path, error }) {
      console.error(`Error in tRPC handler on path '${path}':`, error);
    },
  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
});

(async () => {
  try {
    await server.listen({ port: 3000 });
    console.log('Listening on http://localhost:3000');
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
})();

Core Patterns

WebSocket subscriptions with @fastify/websocket

import ws from '@fastify/websocket';
import {
  fastifyTRPCPlugin,
  FastifyTRPCPluginOptions,
} from '@trpc/server/adapters/fastify';
import fastify from 'fastify';
import { createContext } from './context';
import { appRouter, type AppRouter } from './router';

const server = fastify({
  routerOptions: { maxParamLength: 5000 },
});

// Register @fastify/websocket BEFORE the tRPC plugin
server.register(ws);

server.register(fastifyTRPCPlugin, {
  prefix: '/trpc',
  useWSS: true,
  trpcOptions: {
    router: appRouter,
    createContext,
    keepAlive: {
      enabled: true,
      pingMs: 30000,
      pongWaitMs: 5000,
    },
  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
});

server.listen({ port: 3000 });

Install: npm install @fastify/websocket (minimum version 3.11.0)

Type-safe onError with satisfies

server.register(fastifyTRPCPlugin, {
  prefix: '/trpc',
  trpcOptions: {
    router: appRouter,
    createContext,
    onError({ path, error, type, input }) {
      console.error(`[${type}] ${path}:`, error.message);
    },
  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
});

Due to Fastify plugin type inference limitations, use satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'] to get correct types on onError and other callbacks.

Limiting batch size with maxBatchSize

server.register(fastifyTRPCPlugin, {
  prefix: '/trpc',
  trpcOptions: {
    router: appRouter,
    createContext,
    maxBatchSize: 10,
  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
});

Requests batching more than maxBatchSize operations are rejected with a 400 Bad Request error. Set maxItems on your client's httpBatchLink to the same value to avoid exceeding the limit.

Common Mistakes

HIGH Registering @fastify/websocket after tRPC plugin

Wrong:

server.register(fastifyTRPCPlugin, {
  useWSS: true,
  trpcOptions: { router: appRouter, createContext },
});
server.register(ws); // too late!

Correct:

server.register(ws); // register FIRST
server.register(fastifyTRPCPlugin, {
  useWSS: true,
  trpcOptions: { router: appRouter, createContext },
});

The WebSocket plugin must be registered before the tRPC plugin. Reverse order causes WebSocket routes to not be recognized.

Source: www/docs/server/adapters/fastify.md

HIGH Missing maxParamLength for batch requests

Wrong:

const server = fastify();

Correct:

const server = fastify({
  routerOptions: { maxParamLength: 5000 },
});

Fastify defaults to maxParamLength: 100. Batch requests from httpBatchLink encode multiple procedure names in the URL path parameter, which easily exceeds 100 characters and returns a 404.

Source: www/docs/server/adapters/fastify.md

CRITICAL Using Fastify v4 with tRPC v11

Wrong:

{ "dependencies": { "fastify": "^4.0.0" } }

Correct:

{ "dependencies": { "fastify": "^5.0.0" } }

tRPC v11 requires Fastify v5+. Fastify v4 may return empty responses without errors due to incompatible response handling.

Source: www/docs/server/adapters/fastify.md

See Also

• server-setup -- initTRPC.create(), router/procedure definition, context
• subscriptions -- async generator subscriptions, tracked(), keepAlive
• adapter-standalone -- simpler adapter when Fastify features are not needed
• Fastify docs: https://fastify.dev/docs/latest/