tRPC mit React und Next.js einrichten

Installieren Sie @trpc/server und @trpc/client als zentrale tRPC-Pakete. Fügen Sie @trpc/react-query als Adapter für React-Hooks und @tanstack/react-query als Peer-Abhängigkeit hinzu, die die Hooks bereitstellt.

Für die Integration in Next.js-API-Routen wird in aktuellen tRPC-Versionen kein zusätzliches Adapterpaket benötigt.

Erstellen Sie die Datei server/trpc.ts und rufen Sie initTRPC.create() auf, um das t-Objekt zu erhalten. Exportieren Sie t.router als router, t.procedure als publicProcedure und t.mergeRouters als Hilfsfunktion.

Die initTRPC-Factory akzeptiert ein Generic für den Kontexttyp, das festlegt, welche Daten im ctx-Argument jeder Procedure verfügbar sind.

Eine Procedure wird definiert, indem Sie .input(zodSchema).query(handler) oder .mutation(handler) an publicProcedure anhängen. Für einen einfachen Hello-Endpunkt gilt: publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name).

Das Zod-Schema stellt sowohl TypeScript-Typen als auch eine Validierung der Eingaben zur Laufzeit bereit.

Erstellen Sie mit der Funktion router() einen appRouter: router({ hello: helloHandler, users: usersRouter }). Verschachtelte Router ermöglichen es Ihnen, Procedures nach Fachbereich (users, posts, comments) in separaten Dateien zu organisieren.

Exportieren Sie den AppRouter-Typ: export type AppRouter = typeof appRouter. Diesen Typ importiert der Client.

Erstellen Sie app/api/trpc/[trpc]/route.ts (App Router) oder pages/api/trpc/[trpc].ts (Pages Router). Verwenden Sie fetchRequestHandler aus @trpc/server/adapters/fetch, um alle tRPC-Anfragen über diese einzelne Catch-all-Route zu verarbeiten.

Übergeben Sie fetchRequestHandler den Router, die createContext-Funktion sowie die Request- und Response-Objekte.

Erstellen Sie die Datei utils/trpc.ts. Rufen Sie createTRPCReact() auf, um das typisierte trpc-Clientobjekt zu erstellen. Dieses Objekt verfügt für jede Procedure in Ihrem Router über eine Eigenschaft, die jeweils React-Query-Hooks bereitstellt.

Der AppRouter-Typ wird aus Ihrer Serverdatei importiert. TypeScript folgt der Importkette, um alle Verwendungen zu überprüfen.

Erstellen Sie in Ihrem App-Layout oder in _app.tsx eine QueryClient-Instanz und eine tRPC-Clientinstanz mit trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] }).

Umschließen Sie Ihren Komponentenbaum sowohl mit trpc.Provider (mit dem tRPC-Client) als auch mit QueryClientProvider (mit dem QueryClient). Beide Provider sind erforderlich.

Verwenden Sie in jeder Komponente: const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' }). Der Hook ist vollständig typisiert: data entspricht dem abgeleiteten Rückgabetyp der hello-Procedure, und das Eingabeobjekt wird anhand des Zod-Schemas auf seinen Typ geprüft.

Die Übergabe eines Eingabetyps, der nicht korrekt ist, führt zu einem TypeScript-Kompilierfehler und nicht zu einem Fehler zur Laufzeit.

Damit tRPC funktioniert, muss der Client Typen aus der Serverdatei importieren können. In einem Next.js-Projekt werden Server- und Clientcode innerhalb derselben TypeScript-Kompilierung verarbeitet, sodass die Importe direkt funktionieren.

Konfigurieren Sie in einem Monorepo mit getrennten Paketen TypeScript-Projektreferenzen oder Pfad-Aliase in tsconfig.json, die auf das Serverpaket verweisen.

Der tRPC-Handler wird auf dem Server ausgeführt (als Next.js-API-Route oder Edge Function). Der tRPC-Client läuft im Browser. TypeScript wertet typbezogene Importe zur Build-Zeit aus, ohne Servercode im Browser auszuführen.

Auf dem Client wird nur der AppRouter-Typ importiert, nicht die eigentliche Implementierung. Daher gelangen keine Servergeheimnisse in das Client-Bundle.

Starten Sie den Next.js-Entwicklungsserver und öffnen Sie die Browserkonsole. Der Aufruf trpc.hello.useQuery sollte die Serverantwort protokollieren. Überprüfen Sie im Tab „Network“ die HTTP-Anfrage an /api/trpc/hello, bei der die Eingabe als Query-Parameter gebündelt wird.

Der standardmäßige httpBatchLink fasst mehrere gleichzeitige Anfragen zu einem HTTP-Aufruf zusammen, was im Netzwerk-Wasserfalldiagramm sichtbar ist.

Welche Funktion initialisiert die tRPC-Instanz und stellt die Factorys für Router und Procedures bereit?

Installieren Sie @trpc/server, @trpc/client, @trpc/react-query und @tanstack/react-query. Initialisieren Sie tRPC mit initTRPC.create(), definieren Sie Procedures und exportieren Sie den AppRouter-Typ. Erstellen Sie die Next.js-Catch-all-Route für die API, richten Sie TRPCProvider und QueryClientProvider ein und rufen Sie Procedures mit trpc.procedureName.useQuery() auf.

TypeScript erzwingt den gesamten Client-Server-Vertrag zur Kompilierzeit, ohne dass eine Codegenerierung erforderlich ist.