Adaptateur Fastify

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Exemple d'application

La meilleure façon de démarrer avec l'adaptateur Fastify est de consulter l'exemple d'application.

Description	Links
Fastify server with WebSocket Simple tRPC client in node	CodeSandbox Source

Utiliser tRPC avec Fastify

Installer les dépendances

bash
yarn add @trpc/server fastify zod

bash
yarn add @trpc/server fastify zod

Zod n'est pas obligatoire mais est utilisé dans l'exemple de routeur ci-dessous.

Créer le routeur

Vous devez d'abord créer un routeur pour gérer vos requêtes, mutations et abonnements.

Un exemple de routeur est fourni ci-dessous - enregistrez-le dans un fichier router.ts.

router.ts

router.ts
ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
type User = {
  id: string;
  name: string;
  bio?: string;
};
const users: Record<string, User> = {};
export const t = initTRPC.create();
export const appRouter = t.router({
  getUserById: t.procedure.input(z.string()).query((opts) => {
    return users[opts.input]; // input type is string
  }),
  createUser: t.procedure
    .input(
      z.object({
        name: z.string().min(3),
        bio: z.string().max(142).optional(),
      }),
    )
    .mutation((opts) => {
      const id = Date.now().toString();
      const user: User = { id, ...opts.input };
      users[user.id] = user;
      return user;
    }),
});
// export type definition of API
export type AppRouter = typeof appRouter;

router.ts
ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
type User = {
  id: string;
  name: string;
  bio?: string;
};
const users: Record<string, User> = {};
export const t = initTRPC.create();
export const appRouter = t.router({
  getUserById: t.procedure.input(z.string()).query((opts) => {
    return users[opts.input]; // input type is string
  }),
  createUser: t.procedure
    .input(
      z.object({
        name: z.string().min(3),
        bio: z.string().max(142).optional(),
      }),
    )
    .mutation((opts) => {
      const id = Date.now().toString();
      const user: User = { id, ...opts.input };
      users[user.id] = user;
      return user;
    }),
});
// export type definition of API
export type AppRouter = typeof appRouter;

Si votre routeur devient trop volumineux, découpez-le en sous-routeurs autonomes dans des fichiers séparés, puis fusionnez-les dans un routeur racine appRouter.

Créer le contexte

Vous devez ensuite définir un contexte généré pour chaque requête.

Exemple de contexte à enregistrer dans context.ts :

context.ts

context.ts
ts
import { CreateFastifyContextOptions } from '@trpc/server/adapters/fastify';
export function createContext({ req, res }: CreateFastifyContextOptions) {
  const user = { name: req.headers.username ?? 'anonymous' };
  return { req, res, user };
}
export type Context = Awaited<ReturnType<typeof createContext>>;

context.ts
ts
import { CreateFastifyContextOptions } from '@trpc/server/adapters/fastify';
export function createContext({ req, res }: CreateFastifyContextOptions) {
  const user = { name: req.headers.username ?? 'anonymous' };
  return { req, res, user };
}
export type Context = Awaited<ReturnType<typeof createContext>>;

Créer le serveur Fastify

tRPC inclut nativement un adaptateur pour Fastify. Cet adaptateur vous permet de convertir votre routeur tRPC en plugin Fastify. Pour éviter les erreurs lors de requêtes batch volumineuses, assurez-vous de définir l'option maxParamLength de Fastify à une valeur appropriée, comme illustré.

astuce

En raison des limitations du système de plugins et de l'inférence de types de Fastify, vous pourriez rencontrer des problèmes pour typer correctement onError. Vous pouvez ajouter satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'] pour aider TypeScript et obtenir les types corrects.

server.ts
ts
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({
  maxParamLength: 5000,
});
server.register(fastifyTRPCPlugin, {
  prefix: '/trpc',
  trpcOptions: {
    router: appRouter,
    createContext,
    onError({ path, error }) {
      // report to error monitoring
      console.error(`Error in tRPC handler on path '${path}':`, error);
    },
  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
});
(async () => {
  try {
    await server.listen({ port: 3000 });
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
})();

server.ts
ts
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({
  maxParamLength: 5000,
});
server.register(fastifyTRPCPlugin, {
  prefix: '/trpc',
  trpcOptions: {
    router: appRouter,
    createContext,
    onError({ path, error }) {
      // report to error monitoring
      console.error(`Error in tRPC handler on path '${path}':`, error);
    },
  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
});
(async () => {
  try {
    await server.listen({ port: 3000 });
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
})();

Vos endpoints sont maintenant disponibles via HTTP !

Endpoint	HTTP URI
getUser	GET http://localhost:3000/trpc/getUserById?input=INPUT where INPUT is a URI-encoded JSON string.
createUser	POST http://localhost:3000/trpc/createUser with req.body of type User

Activer les abonnements (WebSocket)

L'adaptateur Fastify prend en charge les abonnements via le plugin @fastify/websocket. En complément des étapes précédentes, il vous suffit d'installer cette dépendance, d'ajouter des abonnements à votre routeur et d'activer l'option useWSS dans le plugin. La version minimale de Fastify requise pour @fastify/websocket est la 3.11.0.

Installer les dépendances

bash
yarn add @fastify/websocket

bash
yarn add @fastify/websocket

Importer et enregistrer @fastify/websocket

ts
import ws from '@fastify/websocket';
server.register(ws);

ts
import ws from '@fastify/websocket';
server.register(ws);

Ajouter des subscriptions

Modifiez le fichier router.ts créé précédemment et ajoutez le code suivant :

router.ts
ts
import { initTRPC } from '@trpc/server';
import { observable } from '@trpc/server/observable';
const t = initTRPC.create();
export const appRouter = t.router({
  randomNumber: t.procedure.subscription(() => {
    return observable<{ randomNumber: number }>((emit) => {
      const timer = setInterval(() => {
        emit.next({ randomNumber: Math.random() });
      }, 1000);
      return () => {
        clearInterval(timer);
      };
    });
  }),
});

router.ts
ts
import { initTRPC } from '@trpc/server';
import { observable } from '@trpc/server/observable';
const t = initTRPC.create();
export const appRouter = t.router({
  randomNumber: t.procedure.subscription(() => {
    return observable<{ randomNumber: number }>((emit) => {
      const timer = setInterval(() => {
        emit.next({ randomNumber: Math.random() });
      }, 1000);
      return () => {
        clearInterval(timer);
      };
    });
  }),
});

Activer l'option useWSS

server.ts
ts
server.register(fastifyTRPCPlugin, {
  useWSS: true,
  // ...
});

server.ts
ts
server.register(fastifyTRPCPlugin, {
  useWSS: true,
  // ...
});

C'est prêt ! Vous pouvez maintenant vous abonner au topic randomNumber et vous recevrez un nombre aléatoire chaque seconde 🚀.

Options du plugin Fastify

name	type	optional	default	description
prefix	string	true	"/trpc"
useWSS	boolean	true	false
trpcOptions	NodeHTTPHandlerOptions	false	n/a