Integrare tRPC con React Query e autenticazione

Il contesto tRPC è un oggetto creato da zero per ogni richiesta dalla funzione createTRPCContext. Può contenere il client del database, la sessione autenticata, le intestazioni della richiesta o qualsiasi altro dato per richiesta di cui le procedure hanno bisogno.

La creazione del contesto avviene prima di qualsiasi procedura, quindi questo è il posto giusto per configurare l'autenticazione e la connessione al database.

In createTRPCContext, chiami getServerSession(authOptions) da next-auth/next. Alleghi il risultato all'oggetto del contesto: return { session: await getServerSession(authOptions), db }. Ora tutte le procedure hanno accesso a ctx.session.

Se session è null, l'utente non è autenticato. Le procedure possono verificarlo per restituire dati in modo condizionale o generare un errore.

Definisca un middleware che verifichi ctx.session: const isAuthenticated = t.middleware(({ ctx, next }) => { if (!ctx.session) throw new TRPCError({ code: 'UNAUTHORIZED' }); return next({ ctx: { session: ctx.session } }); }).

La chiamata next() passa il contesto ristretto, con una sessione non nulla, ai middleware successivi e al gestore della procedura.

Componi il middleware con publicProcedure: const protectedProcedure = publicProcedure.use(isAuthenticated). Ora qualsiasi gestore definito con protectedProcedure.query() o protectedProcedure.mutation() dispone automaticamente di una sessione non nulla in ctx.

TypeScript deduce che ctx.session non è null all'interno delle procedure protette, perché il middleware avrebbe generato un errore prima di raggiungere il gestore.

Sostituisca publicProcedure con protectedProcedure per gli endpoint che richiedono l'autenticazione: protectedProcedure.query(({ ctx }) => getProfileFor(ctx.session.user.id)). TypeScript sa che ctx.session non è null in questo punto, quindi l'accesso a ctx.session.user.id è sicuro senza un controllo su null.

Le richieste non autenticate ricevono automaticamente una risposta 401 UNAUTHORIZED prima dell'esecuzione del gestore.

Passi una funzione headers a httpBatchLink: links: [httpBatchLink({ url: '/api/trpc', headers: async () => { const token = await getToken(); return { Authorization: 'Bearer ' + token }; } })]. La funzione viene eseguita prima di ogni gruppo di richieste.

Questa soluzione viene utilizzata quando si autentica tRPC da un client React Native o da qualsiasi client non Next.js che gestisce autonomamente i propri token di autenticazione.

Per il rendering lato server con il Pages Router di Next.js, crei un helper lato server: createServerSideHelpers({ router: appRouter, ctx: await createContext({ req, res }) }). Utilizzi helpers.post.getAll.prefetch() in getServerSideProps.

Disidrati lo stato precaricato con dehydrate(queryClient) e passalo come props. Sul client, QueryClient si idrata a partire da questo stato, evitando il recupero iniziale al primo caricamento.

Avvolga il file _app.tsx di Next.js con Hydrate da @tanstack/react-query. Passi pageProps.trpcState alla prop state. In questo modo, la cache delle query precaricata viene ripristinata sul client a partire dallo stato serializzato dal server.

Con questa configurazione, gli utenti visualizzano immediatamente pagine completamente popolate, senza indicatori di caricamento lato client durante la navigazione iniziale.

Generi TRPCError con codici semantici HTTP appropriati: UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), BAD_REQUEST (400), INTERNAL_SERVER_ERROR (500). Il client tRPC associa questi codici agli stati di errore appropriati nel risultato dell'hook.

Il campo message può contenere dettagli destinati all'utente, ma in produzione eviti di divulgare informazioni sensibili del server nei messaggi di errore.

tRPC funziona con i client React Native utilizzando lo stesso tipo AppRouter. Sostituisca httpBatchLink con httpLink (fetch di RN funziona allo stesso modo) e configuri le intestazioni di autenticazione. L'adapter @trpc/react-query funziona in modo identico alla configurazione web.

Ciò significa che un monorepo può condividere un unico router tRPC tra un'app web Next.js e un'app Expo React Native, con piena sicurezza dei tipi su entrambe.

Estenda lo schema del middleware per l'accesso basato sui ruoli: verifichi ctx.session.user.role e generi TRPCError({ code: 'FORBIDDEN' }) se il ruolo non è sufficiente. Crei adminProcedure = publicProcedure.use(isAdmin) per gli endpoint riservati agli amministratori.

Impili più middleware per autorizzazioni complesse: publicProcedure.use(isAuthenticated).use(hasFeatureFlag('beta')).query(...).

Come si crea una procedura protetta in tRPC per imporre l'autenticazione?

Il contesto tRPC viene creato per ogni richiesta e contiene la sessione, il client del database e altri dati con ambito limitato alla richiesta. Le procedure protette vengono create componendo un middleware che verifica la sessione con publicProcedure tramite .use(). Il rendering lato server utilizza createServerSideHelpers per il precaricamento e Hydrate per ripristinare la cache sul client.

Le intestazioni di autenticazione per i client non Next.js vengono passate tramite l'opzione headers di httpBatchLink.