Le problème résolu par tRPC

Lorsque vous développez une API REST en TypeScript, le serveur définit la forme de la réponse. Le client doit créer manuellement des types TypeScript correspondants. Ces types dérivent au fil de l'évolution de l'API, et le compilateur ne peut pas détecter l'incompatibilité, car les types sont définis dans des paquets distincts.

Un champ renommé sur le serveur devient un problème silencieux à l'exécution côté client.

GraphQL résout la dérive des types en générant des types TypeScript à partir du schéma avec des outils comme graphql-codegen. Cette approche fonctionne bien, mais elle ajoute de la complexité : un langage de requête distinct (GraphQL SDL), une étape de génération de code dans la chaîne de compilation et des outils de gestion du schéma.

Pour les équipes qui utilisent déjà GraphQL, la génération de code est la bonne solution. Pour celles qui veulent la sécurité des types sans le surcoût de GraphQL, tRPC constitue une autre possibilité.

L'approche de tRPC se distingue par sa grande simplicité : définissez vos procédures d'API sur le serveur sous forme de fonctions TypeScript, exportez le type du routeur, puis importez ce type côté client. Aucune génération de code. Aucun langage de schéma distinct.

Le compilateur TypeScript lui-même fait respecter le contrat entre le client et le serveur au moment de la compilation.

tRPC exige que le serveur et le client partagent leurs types via des importations TypeScript. Cela fonctionne naturellement dans un monodépôt (Turborepo, Nx, pnpm workspaces), où le serveur et le client sont des paquets distincts pouvant s'importer mutuellement.

Pour un serveur et une interface utilisateur entièrement séparés, vous devrez publier les types du routeur dans un paquet partagé. Cela ajoute une étape de publication, mais ne nécessite toujours pas de génération de code.

Sur le serveur, vous définissez un routeur et exportez son type : export type AppRouter = typeof appRouter. Sur le client, vous importez ce type et créez un client typé : createTRPCReact(). Le client connaît exactement les procédures disponibles ainsi que leurs types d'entrée et de sortie.

Le renommage d'une procédure sur le serveur fait immédiatement apparaître une erreur TypeScript côté client.

Comme tRPC utilise directement le système de types de TypeScript, votre éditeur fournit une autocomplétion complète des noms de procédures, des formes d'entrée et des types de retour côté client. Renommer une procédure est une refactorisation de renommage TypeScript, et non une recherche-remplacement manuelle dans toute la base de code.

Cette amélioration de l'expérience de développement est, en pratique, la fonctionnalité de tRPC la plus appréciée.

Par défaut, tRPC utilise HTTP comme transport. Chaque appel de procédure est une requête HTTP. tRPC prend également en charge WebSockets pour les abonnements. Le transport est un détail d'implémentation ; l'API cliente est identique quel que soit le transport.

Vous pouvez aussi exposer les procédures tRPC sous forme de points de terminaison REST classiques grâce à l'adaptateur REST, afin d'assurer la compatibilité avec les clients non-tRPC.

tRPC fonctionne comme intergiciel dans Express, Fastify et Hono. Pour Next.js, il s'intègre via des gestionnaires de routes d'API. Le modèle de démarrage create-t3-app (T3 Stack) regroupe tRPC, Prisma, NextAuth et Tailwind dans un modèle Next.js complet.

T3 Stack est le point de départ tRPC le plus populaire et présente des schémas prêts pour la production.

Une autre approche REST offrant la sécurité des types consiste à définir des schémas Zod, à générer automatiquement une spécification OpenAPI, puis à générer des types TypeScript à partir de cette spécification. Elle fournit un contrat d'API utilisable par des clients qui n'emploient pas TypeScript.

tRPC est plus simple, mais réservé à TypeScript. OpenAPI+Zod ajoute de la complexité, mais produit un contrat d'API public. Choisissez tRPC pour les communications internes entre TypeScript ; choisissez OpenAPI pour les API publiques.

tRPC ne remplace pas REST lorsque vous avez besoin d'une API publique utilisée par des tiers, de clients mobiles qui ne sont pas écrits en TypeScript ou de partenaires ayant besoin d'un contrat stable et versionné. tRPC est spécifiquement destiné aux monodépôts TypeScript offrant une sécurité des types de bout en bout.

Comprendre cette portée vous évite d'adopter tRPC dans des contextes où REST ou GraphQL conviendrait mieux.

L’exécution de npm create t3-app@latest génère la structure d’un projet Next.js avec tRPC, Prisma, NextAuth.js, Tailwind CSS et TypeScript préconfigurés. Le code généré montre la structure du routeur, la création du contexte et la configuration du client.

Étudier cette structure de départ est le moyen le plus rapide de comprendre comment tous les éléments de tRPC s’intègrent dans une véritable application.

Comment tRPC partage-t-il les types entre le serveur et le client sans génération de code ?

tRPC résout la divergence des types entre le client et le serveur TypeScript en partageant directement le type TypeScript du routeur par importation, ce qui élimine la génération de code. Il fonctionne dans les monodépôts et s’intègre à Next.js, Express, Fastify et Hono. La T3 Stack (create-t3-app) constitue la base de démarrage standard pour la production.

tRPC est réservé à TypeScript et convient surtout aux applications internes couvrant toute la pile, plutôt qu’aux API publiques.