Integrando tRPC com React Query e autenticação

O contexto do tRPC é um objeto criado do zero para cada requisição pela função createTRPCContext. Ele pode conter o cliente do banco de dados, a sessão autenticada, os cabeçalhos da requisição ou quaisquer dados por requisição de que seus procedimentos precisem.

A criação do contexto ocorre antes de qualquer procedimento, o que faz dela o local adequado para configurar a autenticação e a conexão com o banco de dados.

Em createTRPCContext, chame getServerSession(authOptions) de next-auth/next. Anexe o resultado ao objeto de contexto: return { session: await getServerSession(authOptions), db }. Agora, todos os procedimentos têm acesso a ctx.session.

Se session for null, o usuário não estará autenticado. Os procedimentos podem verificar isso para retornar dados condicionalmente ou lançar um erro.

Defina uma camada intermediária que verifique ctx.session: const isAuthenticated = t.middleware(({ ctx, next }) => { if (!ctx.session) throw new TRPCError({ code: 'UNAUTHORIZED' }); return next({ ctx: { session: ctx.session } }); }).

A chamada next() passa o contexto restringido (com uma sessão não nula) para as camadas intermediárias seguintes e para o manipulador do procedimento.

Combine a camada intermediária com publicProcedure: const protectedProcedure = publicProcedure.use(isAuthenticated). Agora, qualquer manipulador definido com protectedProcedure.query() ou protectedProcedure.mutation() terá automaticamente uma sessão não nula em ctx.

TypeScript infere que ctx.session não é nulo dentro dos procedimentos protegidos porque a camada intermediária teria lançado um erro antes de o manipulador ser alcançado.

Substitua publicProcedure por protectedProcedure nos pontos de acesso que exigem autenticação: protectedProcedure.query(({ ctx }) => getProfileFor(ctx.session.user.id)). TypeScript sabe que ctx.session não é nulo aqui, portanto acessar ctx.session.user.id é seguro sem uma verificação de nulo.

As solicitações não autenticadas recebem automaticamente uma resposta 401 UNAUTHORIZED antes da execução do manipulador.

Passe uma função de cabeçalhos para httpBatchLink: links: [httpBatchLink({ url: '/api/trpc', headers: async () => { const token = await getToken(); return { Authorization: 'Bearer ' + token }; } })]. A função é executada antes de cada lote de solicitações.

Isso é usado ao autenticar o tRPC a partir de um cliente React Native ou de qualquer cliente que não seja Next.js e gerencie seus próprios tokens de autenticação.

Para SSR no Pages Router do Next.js, crie um auxiliar no servidor: createServerSideHelpers({ router: appRouter, ctx: await createContext({ req, res }) }). Use helpers.post.getAll.prefetch() em getServerSideProps.

Desidrate o estado previamente obtido com dehydrate(queryClient) e passe-o como propriedades. No cliente, o QueryClient hidrata-se a partir desse estado, evitando uma nova busca no primeiro carregamento.

Envolva o _app.tsx do Next.js com Hydrate de @tanstack/react-query. Passe pageProps.trpcState para a propriedade state. Isso restaura no cliente o cache de consultas previamente obtido a partir do estado serializado do servidor.

Com essa configuração, os usuários veem páginas totalmente preenchidas imediatamente, sem indicadores de carregamento no cliente durante a navegação inicial.

Lance TRPCError com códigos semânticos HTTP apropriados: UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), BAD_REQUEST (400), INTERNAL_SERVER_ERROR (500). O cliente tRPC mapeia esses códigos para estados de erro apropriados no resultado do gancho.

O campo message pode conter detalhes voltados ao usuário, mas evite expor informações confidenciais do servidor nas mensagens de erro em produção.

tRPC funciona com clientes React Native usando o mesmo tipo AppRouter. Substitua httpBatchLink por um httpLink (o fetch do RN funciona da mesma forma) e configure os cabeçalhos de autenticação. O adaptador @trpc/react-query funciona de forma idêntica à configuração para a web.

Isso significa que um monorepositório pode compartilhar um único roteador tRPC entre um aplicativo web Next.js e um aplicativo Expo React Native, com segurança completa de tipos em ambos.

Amplie o padrão de camadas intermediárias para o controle de acesso baseado em funções: verifique ctx.session.user.role e lance TRPCError({ code: 'FORBIDDEN' }) se a função for insuficiente. Crie adminProcedure = publicProcedure.use(isAdmin) para pontos de acesso exclusivos de administradores.

Empilhe várias camadas intermediárias para autorizações complexas: publicProcedure.use(isAuthenticated).use(hasFeatureFlag('beta')).query(...).

Como um procedimento protegido é criado no tRPC para aplicar a autenticação?

O contexto do tRPC é criado por requisição e contém a sessão, o cliente do banco de dados e outros dados restritos à requisição. Os procedimentos protegidos são criados combinando uma camada intermediária que verifica a sessão com publicProcedure usando .use(). A renderização no servidor usa createServerSideHelpers para obter dados antecipadamente e Hydrate para restaurar o cache no cliente.

Os cabeçalhos de autenticação para clientes que não sejam Next.js são passados pela opção headers em httpBatchLink.