tRPC en 2026 : construire une API full-stack typée sans jamais écrire une seule route REST

tRPC est une librairie TypeScript qui te permet de créer une API entre ton frontend et ton backend sans jamais définir de schéma REST ni de requête GraphQL. Tu écris du code côté serveur, et tu l’appelles directement depuis le client comme si c’était une simple fonction locale. Le tout avec une autocomplétion parfaite et zéro risque de désynchronisation entre les types.

Si tu as déjà galéré à maintenir une API REST où le backend renvoie un champ user_id et le frontend attend un userId, tu vas comprendre tout de suite pourquoi tRPC cartonne dans l’écosystème JavaScript depuis plusieurs années.

tRPC, c’est quoi concrètement et pourquoi tout le monde en parle ?

tRPC signifie TypeScript Remote Procedure Call : c’est une façon d’appeler des fonctions sur ton serveur depuis ton client, avec les types qui voyagent automatiquement des deux côtés. Pas de code généré, pas de schéma intermédiaire à maintenir. Juste du TypeScript pur qui circule.

Le problème classique quand tu construis une app full-stack, c’est que tu travailles sur deux bases de code séparées. Ton backend et ton frontend ne se parlent que via des appels HTTP. Si tu changes un type côté serveur, ton frontend ne le sait pas. Tu découvres l’erreur en production. Pas idéal.

tRPC résout ce problème d’une façon élégante : tu exportes le type de ton router serveur, tu l’importes dans ton client, et TypeScript fait le reste. Aucune génération de code, aucune synchronisation manuelle. Tu as une source de vérité unique.

C’est pour ça que tRPC est devenu l’outil favori des développeurs qui utilisent Next.js pour leurs projets full-stack. Les deux s’intègrent parfaitement ensemble.

Comment tRPC fonctionne-t-il sous le capot ?

tRPC repose sur un principe simple : tes fonctions serveur sont organisées dans un « router », et ce router expose son type exact au client via un simple import TypeScript.

Voici comment ça se passe en pratique :

1. Tu définis des « procedures » côté serveur (l’équivalent de tes endpoints REST)
2. Tu groupes ces procedures dans un router
3. Tu exportes le type de ce router (pas le code, juste le type)
4. Ton client importe ce type et sait exactement ce qu’il peut appeler et ce qu’il va recevoir

Un exemple minimaliste côté serveur :

// server/router.ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';

const t = initTRPC.create();

export const appRouter = t.router({
  // Une procedure qui retourne un utilisateur par son id
  getUser: t.procedure
    .input(z.object({ id: z.string() })) // validation des inputs
    .query(({ input }) => {
      return { id: input.id, name: 'Alice' };
    }),
});

// On exporte SEULEMENT le type, jamais le code serveur
export type AppRouter = typeof appRouter;

Et côté client :

// client/index.ts
import { createTRPCClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from '../server/router';

const trpc = createTRPCClient<AppRouter>({
  links: [httpBatchLink({ url: 'http://localhost:3000/api/trpc' })],
});

// TypeScript sait exactement ce que getUser attend et retourne
const user = await trpc.getUser.query({ id: '42' });
console.log(user.name); // autocomplétion parfaite ici

Tu remarques que Zod s’intègre naturellement pour valider les inputs. C’est une combinaison très répandue dans l’écosystème.

Quand est-ce que tRPC vaut vraiment le coup, et quand éviter ?

tRPC brille dans un contexte bien précis : quand ton frontend et ton backend sont dans le même dépôt (monorepo) et partagent le même langage TypeScript.

Les cas où tRPC est un excellent choix :

• Une app Next.js full-stack où frontend et backend cohabitent
• Un projet en monorepo avec un frontend React ou Vue et un backend Node.js
• Une équipe réduite qui veut aller vite sans infrastructure API complexe
• Un projet où la maintenabilité des types est une priorité absolue

Les cas où tRPC n’est peut-être pas le bon outil :

• Ton API est consommée par des clients mobiles natifs (iOS, Android) ou des tiers
• Ton backend est en Python, Go ou Java (tRPC est 100% TypeScript)
• Tu as besoin de documenter ton API publiquement avec Swagger ou OpenAPI pour des partenaires externes
• Tu travailles sur un projet qui expose une API à des partenaires externes

En résumé : tRPC est un outil interne. Il ne remplace pas REST ni GraphQL pour les APIs publiques. Mais pour une app interne full-stack TypeScript, c’est difficile de faire mieux.

tRPC vs REST vs GraphQL : lequel choisir selon ton projet ?

Ces trois approches répondent à des besoins différents, et les comparer permet de faire un choix éclairé selon la nature de ton projet.

Comment intégrer tRPC avec React Query pour des données réactives ?

tRPC s’intègre nativement avec TanStack Query (anciennement React Query) pour gérer le cache, les états de chargement et les mutations côté client de façon réactive.

Cette combinaison est la plus populaire dans les projets Next.js. Tu obtiens toute la puissance de React Query (cache automatique, refetch, optimistic updates) avec la sécurité des types de tRPC. Depuis tRPC v11, l’intégration est alignée sur TanStack Query v5 et apporte le support complet de React Suspense.

L’installation se fait en quelques commandes :

# Installation des dépendances principales (tRPC v11)
npm install @trpc/server @trpc/client @trpc/react-query
npm install @tanstack/react-query zod

Et dans ton composant React, ça ressemble à ça :

// Un composant qui fetch un utilisateur avec tRPC + React Query
function UserProfile({ userId }: { userId: string }) {
  // trpc.getUser.useQuery est typé automatiquement
  const { data, isLoading } = trpc.getUser.useQuery({ id: userId });

  if (isLoading) return <p>Chargement...</p>;
  // data.name est typé, pas besoin de cast
  return <p>Bonjour {data?.name}</p>;
}

Pour les mutations (créer, modifier, supprimer des données), tRPC expose un hook useMutation qui fonctionne exactement comme React Query, avec les types en plus. Si tu veux aller plus loin sur la gestion des types en TypeScript, consulte notre article sur les erreurs TypeScript les plus fréquentes.

Quelles sont les erreurs classiques quand on débute avec tRPC ?

Plusieurs erreurs reviennent systématiquement chez les débutants qui prennent tRPC en main pour la première fois.

Importer le code serveur dans le client. tRPC fonctionne parce que tu n’importes que le type du router, jamais le code. Si tu importes accidentellement des modules Node.js dans ton bundle frontend, tu vas avoir des erreurs incompréhensibles. Toujours utiliser import type.

Oublier la validation des inputs. tRPC ne force pas la validation, mais sans elle, n’importe qui peut envoyer n’importe quoi à tes procedures. Utilise toujours Zod (ou Yup) pour valider les entrées de chaque procedure exposée.

Mettre toute la logique dans le router. Le router tRPC doit rester léger. La logique métier appartient à des services séparés que tes procedures appellent. Ça facilite les tests et la maintenance.

Négliger les middlewares pour l’authentification. tRPC a un système de middlewares très propre pour protéger tes procedures. Ne pas l’utiliser et mettre des vérifications manuelles dans chaque procedure, c’est une recette pour les bugs de sécurité.

Comprendre l’architecture sous-jacente aide beaucoup. Si tu veux revoir les bases de Node.js avant de te lancer, c’est une bonne idée.

tRPC est-il compatible avec les environnements edge et serverless ?

tRPC est conçu pour fonctionner dans les environnements modernes, y compris les fonctions serverless et les runtimes edge comme Cloudflare Workers ou Vercel Edge Functions.

Depuis la version 11 (sortie officiellement en mars 2025), tRPC est découplé de tout adapter HTTP spécifique et apporte plusieurs nouveautés importantes : support natif des Server-Sent Events (SSE) pour les subscriptions temps réel, support des types binaires (FormData, Blob, File), et amélioration du support des React Server Components. Il existe des adapters officiels pour :

• Express et Fastify (environnements Node.js classiques)
• Next.js App Router et Pages Router
• Fetch API (compatible avec les runtimes edge)
• AWS Lambda

Cette flexibilité fait de tRPC un bon candidat pour des projets qui visent des déploiements edge. Pour approfondir ce sujet, notre article sur Turso, la base de données SQLite distribuée pour les apps edge, est un bon complément.

En résumé : tRPC

tRPC est l’un des outils les plus élégants de l’écosystème TypeScript pour construire des applications full-stack. Il supprime la friction entre frontend et backend en partageant les types automatiquement, sans génération de code ni schéma à maintenir. Sa version 11, sortie en mars 2025, apporte les SSE pour le temps réel, le support des types binaires et une intégration encore plus poussée avec React Server Components. Il ne convient pas à tout : si tu construis une API publique ou que ton backend n’est pas en TypeScript, REST ou GraphQL restent de meilleures options. Mais pour un projet interne TypeScript de bout en bout, tRPC te fait gagner un temps considérable et élimine toute une catégorie de bugs.

Questions fréquentes sur tRPC

tRPC fonctionne-t-il sans Next.js ?

Oui, tRPC est indépendant de Next.js. Il peut être utilisé avec n’importe quel framework Node.js comme Express ou Fastify côté serveur, et avec n’importe quel framework frontend côté client. Next.js est simplement le contexte le plus courant parce que les deux s’intègrent très bien ensemble.

Est-ce que tRPC remplace GraphQL ?

Non, tRPC et GraphQL répondent à des besoins différents. GraphQL est conçu pour les APIs complexes avec plusieurs clients potentiels, des requêtes flexibles et une documentation formelle. tRPC est conçu pour les apps full-stack TypeScript internes où frontend et backend partagent le même dépôt. Si ton API doit être consommée par des tiers, GraphQL ou REST restent plus adaptés.

Peut-on utiliser tRPC avec Vue.js ou Svelte ?

Oui. tRPC propose un client vanilla qui fonctionne avec n’importe quel framework JavaScript. L’intégration avec React Query est la plus mature, mais des adaptateurs communautaires existent pour Vue.js et Svelte. Tu perds l’intégration native avec les hooks React, mais tu gardes toute la sécurité des types.

tRPC est-il performant pour les grosses applications ?

tRPC supporte le batching de requêtes par défaut, ce qui signifie que plusieurs appels déclenchés au même moment sont regroupés en une seule requête HTTP. Pour les applications avec des besoins en temps réel, tRPC v11 recommande d’utiliser les Server-Sent Events (SSE) en priorité, plus simples à mettre en place que WebSocket et suffisants pour la grande majorité des cas. WebSocket reste disponible pour les scénarios bidirectionnels complexes. Les performances brutes sont comparables à REST sur des cas d’usage standards.

Comment gérer l’authentification avec tRPC ?

tRPC expose un système de middlewares qui te permet de créer des « protected procedures ». Tu crées un middleware qui vérifie la session ou le token JWT, et tu l’appliques aux procedures qui nécessitent une authentification. C’est propre, réutilisable, et bien documenté dans la doc officielle.

Est-ce que tRPC génère une documentation automatique ?

Depuis tRPC v11, il existe un package officiel @trpc/openapi (actuellement en alpha) qui permet de générer une spec OpenAPI directement depuis ton router, sans annotations ni décorateurs. Il infère les types de retour automatiquement à partir de ton implémentation TypeScript. C’est une avancée majeure par rapport à v10 où seules des librairies tierces comme trpc-openapi existaient. La fonctionnalité est encore en alpha, donc pour un besoin de documentation critique en production, REST avec Swagger reste la valeur sûre.