Skip to content
Learni
Voir tous les tutoriels
API & Backend

Comment créer une API type-safe avec tRPC en 2026

18 minBEGINNER
TypeScriptNext.jstRPC
Read in English

Introduction

tRPC permet de créer des APIs TypeScript sans avoir à écrire de définitions OpenAPI ni de contrats manuels. Le typage est partagé automatiquement entre le client et le serveur. Cette approche élimine les erreurs de runtime liées aux données et accélère le développement. En 2026, tRPC reste le choix privilégié pour les projets Next.js qui recherchent simplicité et sécurité de type maximale.

Prérequis

  • Node.js 20 ou supérieur
  • Next.js 15 avec App Router
  • Connaissances de base en TypeScript
  • npm ou pnpm installé

Initialiser le projet Next.js

terminal
npx create-next-app@latest my-trpc-app --yes
cd my-trpc-app
npm install @trpc/server @trpc/client @trpc/react-query @tanstack/react-query zod

Cette commande crée un projet Next.js frais et installe les packages essentiels de tRPC ainsi que Zod pour la validation.

Créer le routeur tRPC principal

src/server/trpc.ts
import { initTRPC } from '@trpc/server';
import superjson from 'superjson';

const t = initTRPC.create({
  transformer: superjson,
});
export const router = t.router;
export const publicProcedure = t.procedure;

Nous initialisons tRPC avec SuperJSON pour supporter les types complexes comme Date. Les exports router et procedure seront réutilisés partout.

Définir les routes API

src/server/routers/user.ts
import { router, publicProcedure } from '../trpc';
import { z } from 'zod';

export const userRouter = router({
  getById: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(async ({ input }) => {
      return { id: input.id, name: 'Alice', email: 'alice@example.com' };
    }),
  create: publicProcedure
    .input(z.object({ name: z.string().min(2) }))
    .mutation(async ({ input }) => {
      return { id: 'new-id', ...input };
    }),
});

Chaque procédure est typée grâce à Zod. getById est une query et create une mutation. Le typage est automatique côté client.

Assembler le routeur racine

src/server/routers/_app.ts
import { router } from '../trpc';
import { userRouter } from './user';

export const appRouter = router({
  user: userRouter,
});
export type AppRouter = typeof appRouter;

Le routeur principal regroupe tous les sous-routeurs. Le type AppRouter est exporté pour le client.

Créer le handler API Next.js

src/app/api/trpc/[trpc]/route.ts
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import { appRouter } from '@/server/routers/_app';

const handler = (req: Request) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext: () => ({}),
  });
export { handler as GET, handler as POST };

Ce fichier expose toutes les procédures tRPC via l'App Router de Next.js. Aucune configuration supplémentaire n'est requise.

Configurer le provider React

src/app/providers.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { httpBatchLink } from '@trpc/client';
import { createTRPCReact } from '@trpc/react-query';
import { AppRouter } from '@/server/routers/_app';
import { useState } from 'react';

export const trpc = createTRPCReact<AppRouter>();
export function TRPCProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient());
  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [httpBatchLink({ url: '/api/trpc' })],
    })
  );
  return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    </trpc.Provider>
  );
}

Le provider connecte React Query et tRPC. Placez-le dans le layout racine pour que tous les composants y aient accès.

Bonnes pratiques

  • Utilisez toujours Zod pour valider les entrées
  • Séparez les routeurs par domaine métier
  • Activez SuperJSON dès le début pour supporter les Dates et Maps
  • Nommez clairement vos procédures (get, create, update, delete)
  • Écrivez des tests d'intégration sur les procédures critiques

Erreurs courantes à éviter

  • Oublier d'exporter le type AppRouter côté serveur
  • Ne pas placer le TRPCProvider dans le layout racine
  • Utiliser des procédures sans input alors que des données sont attendues
  • Ignorer les erreurs de validation Zod qui remontent mal côté client

Pour aller plus loin

Découvrez nos formations complètes sur tRPC et Next.js sur Learni Group.