Il problema risolto da tRPC

Quando crea un'API REST in TypeScript, il server definisce la struttura della risposta. Il client deve creare manualmente i tipi TypeScript corrispondenti. Nel tempo, questi tipi divergono man mano che l'API evolve e il compilatore non può rilevare la discrepanza, perché i tipi sono definiti in pacchetti separati.

Un campo rinominato sul server diventa un bug silenzioso a runtime nel client.

GraphQL risolve la deriva dei tipi generando tipi TypeScript dallo schema con strumenti come graphql-codegen. Questa soluzione funziona bene, ma aggiunge complessità: un linguaggio di query separato (GraphQL SDL), un passaggio di generazione del codice nella pipeline di build e strumenti per la gestione dello schema.

Per i team che hanno già investito in GraphQL, codegen è la risposta giusta. Per i team che desiderano la sicurezza dei tipi senza il sovraccarico aggiuntivo di GraphQL, tRPC offre un'alternativa.

L'approccio di tRPC è radicalmente semplice: definisca le procedure API sul server come funzioni TypeScript, esporti il tipo del router e importi quel tipo nel client. Nessuna generazione del codice. Nessun linguaggio di schema separato.

È il compilatore TypeScript stesso a garantire il contratto tra client e server in fase di build.

tRPC richiede che server e client condividano i tipi tramite importazioni TypeScript. Questo funziona naturalmente in un monorepo (Turborepo, Nx, pnpm workspaces), dove server e client sono pacchetti separati che possono importarsi a vicenda.

Per un backend e un frontend completamente separati, dovrebbe pubblicare i tipi del router come pacchetto condiviso. Questo aggiunge un passaggio di pubblicazione, ma consente comunque di evitare il codegen.

Sul server, definisca un router ed esporti il suo tipo: export type AppRouter = typeof appRouter. Sul client, importi quel tipo e crei un client tipizzato: createTRPCReact(). Il client sa esattamente quali procedure esistono e quali sono i relativi tipi di input e output.

Se rinomina una procedura sul server, sul client viene immediatamente mostrato un errore di TypeScript.

Poiché tRPC utilizza direttamente il sistema di tipi di TypeScript, l'editor offre il completamento automatico completo per i nomi delle procedure, le strutture degli input e i tipi restituiti sul client. Rinominare una procedura è un refactoring di rinomina di TypeScript, non una ricerca e sostituzione manuale nell'intera codebase.

Questo miglioramento dell'esperienza degli sviluppatori è, nella pratica, la funzionalità più apprezzata di tRPC.

Per impostazione predefinita, tRPC utilizza HTTP come trasporto. Ogni chiamata a una procedura è una richiesta HTTP. tRPC supporta anche WebSockets per le subscription. Il trasporto è un dettaglio implementativo; l'API del client è identica indipendentemente dal trasporto.

Può inoltre esporre le procedure tRPC come endpoint REST convenzionali utilizzando l'adattatore REST, per garantire la compatibilità con client non tRPC.

tRPC funziona come middleware in Express, Fastify e Hono. Per Next.js, si integra tramite gli handler delle route API. Lo starter create-t3-app (T3 Stack) combina tRPC, Prisma, NextAuth e Tailwind in un template Next.js full-stack.

Il T3 Stack è il punto di partenza più popolare per tRPC e dimostra pattern pronti per la produzione.

Un altro approccio REST con sicurezza dei tipi consiste nel definire schemi Zod, generare automaticamente una specifica OpenAPI e generare tipi TypeScript a partire dalla specifica. In questo modo si ottiene un contratto API utilizzabile da client non scritti in TypeScript.

tRPC è più semplice, ma funziona solo con TypeScript. OpenAPI+Zod aggiunge complessità, ma produce un contratto API pubblico. Scelga tRPC per la comunicazione interna tra client e server TypeScript; scelga OpenAPI per le API pubbliche.

tRPC non sostituisce REST quando ha bisogno di un'API pubblica utilizzata da terze parti, di client mobili non scritti in TypeScript o di partner che necessitano di un contratto stabile e versionato. È pensato specificamente per i monorepo TypeScript con sicurezza dei tipi full-stack.

Comprendere questo ambito evita di adottare tRPC in contesti in cui REST o GraphQL sono più adatti.

L'esecuzione di npm create t3-app@latest genera la struttura iniziale di un progetto Next.js con tRPC, Prisma, NextAuth.js, Tailwind CSS e TypeScript preconfigurati. Il codice generato mostra la struttura del router, la creazione del context e la configurazione del client.

Studiare questa struttura iniziale è il modo più rapido per capire come tutti i componenti di tRPC si integrano in un'applicazione reale.

In che modo tRPC condivide i tipi tra server e client senza generare codice?

tRPC risolve il problema della deriva dei tipi tra client e server TypeScript condividendo direttamente il tipo TypeScript del router tramite import, senza generare codice. Funziona nei monorepo e si integra con Next.js, Express, Fastify e Hono. Il T3 Stack (create-t3-app) è lo starter standard per la produzione.

tRPC è solo per TypeScript ed è più adatto alle applicazioni full-stack interne che alle API pubbliche.