Configurare tRPC con React e Next.js

Installi @trpc/server e @trpc/client per i pacchetti principali di tRPC. Aggiunga @trpc/react-query per l'adapter degli hook React e @tanstack/react-query come peer dependency che fornisce la funzionalità agli hook.

Per l'integrazione delle API route di Next.js non è necessario alcun pacchetto adapter aggiuntivo nelle versioni recenti di tRPC.

Crei un file server/trpc.ts e chiami initTRPC.create() per ottenere l'oggetto t. Esporti t.router come router, t.procedure come publicProcedure e t.mergeRouters come utility.

La factory initTRPC accetta un generico del tipo context che definisce quali dati sono disponibili nell'argomento ctx di ogni procedura.

Una procedura si definisce concatenando .input(zodSchema).query(handler) oppure .mutation(handler) a publicProcedure. Per un semplice endpoint hello: publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name).

Lo schema Zod fornisce sia i tipi TypeScript sia la validazione a runtime dell'input.

Crei un appRouter usando la funzione router(): router({ hello: helloHandler, users: usersRouter }). I router annidati consentono di organizzare le procedure per dominio (users, posts, comments) in file separati.

Esporti il tipo AppRouter: export type AppRouter = typeof appRouter. È questo il tipo che il client importerà.

Crei app/api/trpc/[trpc]/route.ts (App Router) oppure pages/api/trpc/[trpc].ts (Pages Router). Usi fetchRequestHandler da @trpc/server/adapters/fetch per gestire tutte le richieste tRPC tramite questa singola route catch-all.

Passi a fetchRequestHandler il router, la funzione createContext e gli oggetti request/response.

Crei un file utils/trpc.ts. Chiami createTRPCReact() per creare l'oggetto client trpc tipizzato. Questo oggetto ha una proprietà per ogni procedura del router, e ciascuna espone gli hook di React Query.

L'import del tipo AppRouter proviene dal file del server; TypeScript segue la catena di importazioni per convalidare tutti gli utilizzi.

Nel layout dell'applicazione o in _app.tsx, crei un'istanza di QueryClient e un'istanza del client tRPC usando trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] }).

Avvolga l'albero dei componenti in trpc.Provider (con il client trpc) e in QueryClientProvider (con il QueryClient). Sono necessari entrambi i provider.

In qualsiasi componente: const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' }). L'hook è completamente tipizzato: data è il tipo restituito inferito della procedura hello e l'oggetto input viene verificato rispetto allo schema Zod.

Passare un tipo di input errato genera un errore di compilazione TypeScript, non un errore a runtime.

Per funzionare, tRPC deve poter importare i tipi dal file del server. In un progetto Next.js, il codice del server e quello del client condividono la stessa compilazione TypeScript, quindi gli import funzionano senza altre configurazioni.

In un monorepo con pacchetti separati, configuri i project references di TypeScript o gli alias dei percorsi in tsconfig.json in modo che puntino al pacchetto del server.

Il gestore tRPC viene eseguito sul server, come API route o Edge Function di Next.js. Il client tRPC viene eseguito nel browser. TypeScript valuta gli import a livello di tipo durante la compilazione senza eseguire il codice del server nel browser.

Sul client viene importato solo il tipo AppRouter, non l'implementazione effettiva, quindi i segreti del server non finiscono nel bundle del client.

Avvii il server di sviluppo Next.js e apra la console del browser. La chiamata trpc.hello.useQuery dovrebbe registrare la risposta del server. Controlli la scheda Network per vedere la richiesta HTTP a /api/trpc/hello, con l'input incluso come parametro di query.

Per impostazione predefinita, httpBatchLink combina più richieste concorrenti in un'unica chiamata HTTP, visibile nel grafico delle richieste di rete.

Quale funzione inizializza l'istanza tRPC e fornisce le factory per router e procedure?

Installi @trpc/server, @trpc/client, @trpc/react-query e @tanstack/react-query. Inizializzi tRPC con initTRPC.create(), definisca le procedure ed esporti il tipo AppRouter. Crei la route catch-all delle API di Next.js, configuri TRPCProvider e QueryClientProvider, quindi chiami le procedure con trpc.procedureName.useQuery().

TypeScript applica l'intero contratto tra client e server durante la compilazione, senza generare codice.