tRPC mit React Query und Authentifizierung integrieren

Der tRPC-Kontext ist ein Objekt, das von der Funktion createTRPCContext für jede Anfrage neu erstellt wird. Es kann den Datenbank-Client, die authentifizierte Session, die Anfrage-Header oder beliebige andere anfragespezifische Daten enthalten, die Ihre Procedures benötigen.

Die Kontexterstellung erfolgt vor jeder Procedure und ist daher der richtige Ort für die Authentifizierung und die Einrichtung der Datenbankverbindung.

Rufen Sie in createTRPCContext getServerSession(authOptions) aus next-auth/next auf. Hängen Sie das Ergebnis an das Kontextobjekt an: return { session: await getServerSession(authOptions), db }. Alle Procedures haben nun Zugriff auf ctx.session.

Wenn session den Wert null hat, ist die Benutzerin oder der Benutzer nicht authentifiziert. Procedures können dies prüfen, um abhängig davon Daten zurückzugeben oder einen Fehler auszulösen.

Definieren Sie eine Middleware, die ctx.session prüft: const isAuthenticated = t.middleware(({ ctx, next }) => { if (!ctx.session) throw new TRPCError({ code: 'UNAUTHORIZED' }); return next({ ctx: { session: ctx.session } }); }).

Der Aufruf next() übergibt den eingeengten Kontext (mit einer nicht-null-Session) an nachfolgende Middlewares und den Procedure-Handler.

Verknüpfen Sie die Middleware mit publicProcedure: const protectedProcedure = publicProcedure.use(isAuthenticated). Jede mit protectedProcedure.query() oder protectedProcedure.mutation() definierte Funktion verfügt nun automatisch über eine nicht-null-Session in ctx.

TypeScript erkennt, dass ctx.session innerhalb geschützter Procedures nicht null ist, weil die Middleware vor dem Erreichen des Handlers einen Fehler ausgelöst hätte.

Ersetzen Sie publicProcedure bei Endpunkten, die eine Authentifizierung erfordern, durch protectedProcedure: protectedProcedure.query(({ ctx }) => getProfileFor(ctx.session.user.id)). TypeScript weiß hier, dass ctx.session nicht null ist. Daher kann sicher auf ctx.session.user.id zugegriffen werden, ohne eine Nullprüfung.

Nicht authentifizierte Anfragen erhalten automatisch eine 401-UNAUTHORIZED-Antwort, bevor der Handler ausgeführt wird.

Übergeben Sie eine headers-Funktion an httpBatchLink: links: [httpBatchLink({ url: '/api/trpc', headers: async () => { const token = await getToken(); return { Authorization: 'Bearer ' + token }; } })]. Die Funktion wird vor jedem Batch von Anfragen ausgeführt.

Dies wird verwendet, wenn Sie tRPC über einen React-Native-Client oder einen anderen Nicht-Next.js-Client authentifizieren, der seine Authentifizierungstokens selbst verwaltet.

Für SSR im Pages Router von Next.js erstellen Sie einen serverseitigen Helper: createServerSideHelpers({ router: appRouter, ctx: await createContext({ req, res }) }). Verwenden Sie helpers.post.getAll.prefetch() in getServerSideProps.

Dehydrieren Sie den vorab geladenen Zustand mit dehydrate(queryClient) und übergeben Sie ihn als Props. Auf dem Client hydratisiert der QueryClient aus diesem Zustand, sodass der erneute Abruf beim ersten Laden entfällt.

Umgeben Sie _app.tsx Ihrer Next.js-Anwendung mit Hydrate aus @tanstack/react-query. Übergeben Sie pageProps.trpcState an die state-Prop. Dadurch wird der vorab geladene Query-Cache auf dem Client aus dem serialisierten Serverzustand wiederhergestellt.

Mit dieser Einrichtung sehen Benutzerinnen und Benutzer sofort vollständig geladene Seiten, ohne beim ersten Navigieren clientseitige Ladeindikatoren zu sehen.

Werfen Sie TRPCError mit passenden HTTP-semantischen Codes: UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), BAD_REQUEST (400), INTERNAL_SERVER_ERROR (500). Der tRPC-Client ordnet diese passenden Fehlerzuständen im Hook-Ergebnis zu.

Das Feld message kann für die Benutzeroberfläche bestimmte Details enthalten. Vermeiden Sie es jedoch, in Produktionsfehlermeldungen vertrauliche Serverinformationen preiszugeben.

tRPC funktioniert mit React-Native-Clients unter Verwendung desselben AppRouter-Typs. Ersetzen Sie httpBatchLink durch einen httpLink (RN fetch funktioniert genauso) und konfigurieren Sie die Authentifizierungs-Header. Der @trpc/react-query-Adapter funktioniert genauso wie bei der Webanwendung.

Das bedeutet, dass ein Monorepo einen tRPC-Router zwischen einer Next.js-Webanwendung und einer Expo-React-Native-Anwendung gemeinsam nutzen kann – mit vollständiger Typsicherheit auf beiden Seiten.

Erweitern Sie das Middleware-Muster für die rollenbasierte Zugriffssteuerung: Prüfen Sie ctx.session.user.role und werfen Sie TRPCError({ code: 'FORBIDDEN' }), wenn die Rolle nicht ausreicht. Erstellen Sie adminProcedure = publicProcedure.use(isAdmin) für ausschließlich Administrationszwecken vorbehaltene Endpunkte.

Kombinieren Sie mehrere Middlewares für komplexe Autorisierungsregeln: publicProcedure.use(isAuthenticated).use(hasFeatureFlag('beta')).query(...).

Wie wird in tRPC eine geschützte Procedure erstellt, um die Authentifizierung zu erzwingen?

Der tRPC-Kontext wird pro Anfrage erstellt und enthält die Session, den Datenbank-Client sowie weitere anfragespezifische Daten. Geschützte Procedures werden erstellt, indem mit .use() eine Middleware zur Sitzungsprüfung an publicProcedure angehängt wird. Das serverseitige Rendering verwendet createServerSideHelpers zum Vorabladen und Hydrate zum Wiederherstellen des Caches auf dem Client.

Auth-Header für Nicht-Next.js-Clients werden über die headers-Option von httpBatchLink übergeben.