Configurer tRPC avec React et Next.js

Installez @trpc/server et @trpc/client pour les packages tRPC principaux. Ajoutez @trpc/react-query comme adaptateur des fonctions d’accroche React, ainsi que @tanstack/react-query comme dépendance homologue qui fournit ces fonctions.

Pour intégrer les routes d’API Next.js, aucun package d’adaptation supplémentaire n’est nécessaire dans les versions récentes de tRPC.

Créez un fichier server/trpc.ts et appelez initTRPC.create() pour obtenir l’objet t. Exportez t.router sous le nom de router, t.procedure sous le nom de publicProcedure et t.mergeRouters comme utilitaire.

La fabrique initTRPC accepte un type générique de contexte qui définit les données disponibles dans l’argument ctx de chaque procédure.

Une procédure se définit en chaînant .input(zodSchema).query(handler) ou .mutation(handler) à publicProcedure. Pour un point de terminaison hello simple : publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name).

Le schéma Zod fournit à la fois les types TypeScript et la validation à l’exécution de l’entrée.

Créez un appRouter à l’aide de la fonction router() : router({ hello: helloHandler, users: usersRouter }). Les routeurs imbriqués vous permettent d’organiser les procédures par domaine (users, posts, comments) dans des fichiers distincts.

Exportez le type AppRouter : export type AppRouter = typeof appRouter. C’est ce type que le client importera.

Créez app/api/trpc/[trpc]/route.ts (App Router) ou pages/api/trpc/[trpc].ts (Pages Router). Utilisez fetchRequestHandler de @trpc/server/adapters/fetch pour gérer toutes les requêtes tRPC au moyen de cette route attrape-tout unique.

Transmettez le routeur, la fonction createContext ainsi que les objets de requête et de réponse à fetchRequestHandler.

Créez un fichier utils/trpc.ts. Appelez createTRPCReact() pour créer l’objet client trpc typé. Cet objet possède une propriété pour chaque procédure de votre routeur, chacune exposant des fonctions d’accroche React Query.

L’importation du type AppRouter provient de votre fichier serveur ; TypeScript suit la chaîne d’importations pour valider toutes les utilisations.

Dans la mise en page de votre application ou dans _app.tsx, créez une instance de QueryClient et une instance du client tRPC avec trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] }).

Entourez l’arbre de vos composants avec trpc.Provider (en lui transmettant le client tRPC) et QueryClientProvider (en lui transmettant QueryClient). Les deux fournisseurs sont requis.

Dans n’importe quel composant : const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' }). La fonction d’accroche est entièrement typée : data correspond au type de retour inféré de la procédure hello, et l’objet d’entrée est vérifié par rapport au schéma Zod.

Transmettre un type d’entrée incorrect provoque une erreur de compilation TypeScript, et non une erreur d’exécution.

Pour que tRPC fonctionne, le client doit pouvoir importer des types depuis le fichier serveur. Dans un projet Next.js, le code serveur et le code client partagent la même compilation TypeScript, les importations fonctionnent donc directement.

Dans un monodépôt composé de packages distincts, configurez des références de projets TypeScript ou des alias de chemins dans tsconfig.json afin de pointer vers le package serveur.

Le gestionnaire tRPC s’exécute sur le serveur (comme route d’API Next.js ou fonction en périphérie). Le client tRPC s’exécute dans le navigateur. TypeScript évalue les importations de types au moment de la compilation sans exécuter le code serveur dans le navigateur.

Seul le type AppRouter est importé sur le client, et non l’implémentation réelle : aucun secret du serveur ne se retrouve donc dans le paquet client.

Démarrez le serveur de développement Next.js et ouvrez la console du navigateur. L’appel trpc.hello.useQuery doit afficher la réponse du serveur dans les journaux. Consultez l’onglet Réseau pour voir la requête HTTP vers /api/trpc/hello, avec l’entrée regroupée comme paramètre de requête.

Par défaut, httpBatchLink combine plusieurs requêtes simultanées en un seul appel HTTP, ce qui est visible dans le diagramme des échanges réseau.

Quelle fonction initialise l’instance tRPC et fournit les fabriques de routeurs et de procédures ?

Installez @trpc/server, @trpc/client, @trpc/react-query et @tanstack/react-query. Initialisez tRPC avec initTRPC.create(), définissez les procédures et exportez le type AppRouter. Créez la route d’API attrape-tout de Next.js, configurez TRPCProvider et QueryClientProvider, puis appelez les procédures avec trpc.procedureName.useQuery().

TypeScript applique l’intégralité du contrat client-serveur au moment de la compilation, sans génération de code.