Configurando tRPC com React e Next.js

Instale @trpc/server e @trpc/client, os pacotes centrais do tRPC. Adicione @trpc/react-query como adaptador dos ganchos do React e @tanstack/react-query como a dependência complementar que fornece os ganchos.

Para a integração com rotas de API do Next.js, nenhum pacote de adaptador adicional é necessário nas versões recentes do tRPC.

Crie um arquivo server/trpc.ts e chame initTRPC.create() para obter o objeto t. Exporte t.router como router, t.procedure como publicProcedure e t.mergeRouters como um utilitário.

A fábrica initTRPC aceita um tipo genérico de contexto que define quais dados estão disponíveis no argumento ctx de cada procedimento.

Um procedimento é definido encadeando .input(zodSchema).query(handler) ou .mutation(handler) a publicProcedure. Para um ponto de acesso hello simples: publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name).

O esquema do Zod fornece tanto os tipos do TypeScript quanto a validação em tempo de execução para a entrada.

Crie um appRouter usando a função router(): router({ hello: helloHandler, users: usersRouter }). Os roteadores aninhados permitem organizar os procedimentos por domínio (users, posts, comments) em arquivos separados.

Exporte o tipo AppRouter: export type AppRouter = typeof appRouter. É esse tipo que o cliente importará.

Crie app/api/trpc/[trpc]/route.ts (App Router) ou pages/api/trpc/[trpc].ts (Pages Router). Use fetchRequestHandler de @trpc/server/adapters/fetch para tratar todas as solicitações do tRPC por meio desta única rota abrangente.

Passe o roteador, a função createContext e os objetos de solicitação e resposta para fetchRequestHandler.

Crie um arquivo utils/trpc.ts. Chame createTRPCReact() para criar o objeto cliente trpc tipado. Esse objeto tem uma propriedade para cada procedimento do seu roteador, e cada uma expõe ganchos do React Query.

A importação do tipo AppRouter vem do arquivo do servidor; o TypeScript segue a cadeia de importações para validar todos os usos.

No layout da aplicação ou em _app.tsx, crie uma instância de QueryClient e uma instância do cliente tRPC usando trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] }).

Envolva a árvore de componentes em trpc.Provider (com o cliente tRPC) e em QueryClientProvider (com o QueryClient). Ambos os provedores são necessários.

Em qualquer componente: const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' }). O gancho é totalmente tipado: data é o tipo de retorno inferido do procedimento hello, e o objeto de entrada é verificado em relação ao esquema do Zod.

Passar um tipo de entrada incorreto causa um erro de compilação do TypeScript, não um erro em tempo de execução.

Para que o tRPC funcione, o cliente precisa conseguir importar tipos do arquivo do servidor. Em um projeto Next.js, o código do servidor e do cliente compartilha a mesma compilação do TypeScript, portanto as importações funcionam normalmente.

Em um monorrepositório com pacotes separados, configure referências de projeto do TypeScript ou aliases de caminho em tsconfig.json para apontar para o pacote do servidor.

O manipulador do tRPC é executado no servidor (como uma rota de API do Next.js ou uma função de borda). O cliente do tRPC é executado no navegador. O TypeScript avalia as importações em nível de tipo durante a compilação, sem executar o código do servidor no navegador.

Somente o tipo AppRouter é importado no cliente, não a implementação real, portanto nenhum segredo do servidor vaza para o pacote do cliente.

Inicie o servidor de desenvolvimento do Next.js e abra o console do navegador. A chamada trpc.hello.useQuery deve registrar a resposta do servidor. Verifique a aba Rede para ver a solicitação HTTP para /api/trpc/hello, com a entrada agrupada como um parâmetro de consulta.

O httpBatchLink padrão combina várias solicitações simultâneas em uma única chamada HTTP, visível na cascata de rede.

Qual função inicializa a instância do tRPC e fornece as fábricas de roteadores e procedimentos?

Instale @trpc/server, @trpc/client, @trpc/react-query e @tanstack/react-query. Inicialize o tRPC com initTRPC.create(), defina os procedimentos e exporte o tipo AppRouter. Crie a rota abrangente da API do Next.js, configure TRPCProvider e QueryClientProvider e, em seguida, chame os procedimentos com trpc.procedureName.useQuery().

O TypeScript impõe todo o contrato entre cliente e servidor em tempo de compilação, sem geração de código.