Adapter Fastify

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/