Integración de tRPC con React Query y autenticación

El contexto de tRPC es un objeto que la función createTRPCContext crea desde cero para cada solicitud. Puede contener el cliente de base de datos, la sesión autenticada, las cabeceras de la solicitud o cualquier dato específico de la solicitud que necesiten sus procedimientos.

La creación del contexto se ejecuta antes que cualquier procedimiento, por lo que es el lugar adecuado para configurar la autenticación y la conexión a la base de datos.

En createTRPCContext, llame a getServerSession(authOptions) desde next-auth/next. Adjunte el resultado al objeto de contexto: return { session: await getServerSession(authOptions), db }. Ahora todos los procedimientos tienen acceso a ctx.session.

Si session es null, el usuario no está autenticado. Los procedimientos pueden comprobarlo para devolver datos de forma condicional o lanzar un error.

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

La llamada next() pasa el contexto reducido (con una sesión no nula) a los middlewares posteriores y al controlador del procedimiento.

Combine el middleware con publicProcedure: const protectedProcedure = publicProcedure.use(isAuthenticated). Ahora cualquier controlador definido con protectedProcedure.query() o protectedProcedure.mutation() tiene automáticamente una sesión no nula en ctx.

TypeScript infiere que ctx.session no es nulo dentro de los procedimientos protegidos porque el middleware habría lanzado un error antes de llegar al controlador.

Reemplace publicProcedure por protectedProcedure en los endpoints que requieran autenticación: protectedProcedure.query(({ ctx }) => getProfileFor(ctx.session.user.id)). TypeScript sabe que ctx.session no es nulo aquí, por lo que acceder a ctx.session.user.id es seguro sin comprobar si es nulo.

Las solicitudes no autenticadas reciben automáticamente una respuesta 401 UNAUTHORIZED antes de que se ejecute el controlador.

Pase una función de cabeceras a httpBatchLink: links: [httpBatchLink({ url: '/api/trpc', headers: async () => { const token = await getToken(); return { Authorization: 'Bearer ' + token }; } })]. La función se ejecuta antes de cada lote de solicitudes.

Esto se utiliza al autenticar tRPC desde un cliente de React Native o desde cualquier cliente que no sea de Next.js y administre sus propios tokens de autenticación.

Para SSR en el Pages Router de Next.js, cree un helper del lado del servidor: createServerSideHelpers({ router: appRouter, ctx: await createContext({ req, res }) }). Utilice helpers.post.getAll.prefetch() en getServerSideProps.

Deshidrate el estado precargado con dehydrate(queryClient) y páselo como props. En el cliente, QueryClient hidrata sus datos a partir de este estado, lo que evita volver a obtenerlos durante la carga inicial.

Envuelva su _app.tsx de Next.js con Hydrate de @tanstack/react-query. Pase pageProps.trpcState a la propiedad state. Esto restaura en el cliente la caché de consultas precargada a partir del estado serializado del servidor.

Con esta configuración, los usuarios ven las páginas completamente cargadas de inmediato, sin indicadores de carga del cliente durante la navegación inicial.

Lance TRPCError con códigos semánticos HTTP adecuados: UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), BAD_REQUEST (400), INTERNAL_SERVER_ERROR (500). El cliente de tRPC asigna estos códigos a los estados de error correspondientes en el resultado del hook.

El campo message puede contener detalles visibles para el usuario, pero evite revelar información confidencial del servidor en los mensajes de error de producción.

tRPC funciona con clientes de React Native utilizando el mismo tipo AppRouter. Reemplace httpBatchLink por httpLink (RN fetch funciona de la misma manera) y configure las cabeceras de autenticación. El adaptador @trpc/react-query funciona igual que en la configuración web.

Esto significa que un monorepo puede compartir un único router de tRPC entre una aplicación web de Next.js y una aplicación de Expo React Native, con seguridad de tipos completa en ambas.

Amplíe el patrón de middleware para controlar el acceso según los roles: compruebe ctx.session.user.role y lance TRPCError({ code: 'FORBIDDEN' }) si el rol no tiene permisos suficientes. Cree adminProcedure = publicProcedure.use(isAdmin) para los endpoints exclusivos de administradores.

Combine varios middlewares para crear una autorización compleja: publicProcedure.use(isAuthenticated).use(hasFeatureFlag('beta')).query(...).

¿Cómo se crea un procedimiento protegido en tRPC para imponer la autenticación?

El contexto de tRPC se crea para cada solicitud y contiene la sesión, el cliente de base de datos y otros datos específicos de la solicitud. Los procedimientos protegidos se crean combinando un middleware que comprueba la sesión con publicProcedure mediante .use(). El renderizado del lado del servidor utiliza createServerSideHelpers para precargar datos y Hydrate para restaurar la caché en el cliente.

Las cabeceras de autenticación para clientes que no sean de Next.js se pasan mediante la opción headers de httpBatchLink.