Configurar tRPC con React y Next.js

Instale @trpc/server y @trpc/client para obtener los paquetes principales de tRPC. Añada @trpc/react-query para el adaptador de hooks de React y @tanstack/react-query como dependencia peer que proporciona la funcionalidad de los hooks.

Para integrar rutas de API de Next.js, en las versiones recientes de tRPC no se necesita ningún paquete de adaptador adicional.

Cree un archivo server/trpc.ts y llame a initTRPC.create() para obtener el objeto t. Exporte t.router como router, t.procedure como publicProcedure y t.mergeRouters como utilidad.

La fábrica initTRPC acepta un genérico de tipo de contexto que define qué datos están disponibles en el argumento ctx de cada procedimiento.

Un procedimiento se define encadenando .input(zodSchema).query(handler) o .mutation(handler) a publicProcedure. Para obtener un endpoint hello sencillo: publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name).

El esquema de Zod proporciona tanto los tipos de TypeScript como la validación en tiempo de ejecución para la entrada.

Cree un appRouter mediante la función router(): router({ hello: helloHandler, users: usersRouter }). Los routers anidados le permiten organizar los procedimientos por dominio (users, posts, comments) en archivos separados.

Exporte el tipo AppRouter: export type AppRouter = typeof appRouter. Este es el tipo que importará el cliente.

Cree app/api/trpc/[trpc]/route.ts (App Router) o pages/api/trpc/[trpc].ts (Pages Router). Use fetchRequestHandler de @trpc/server/adapters/fetch para gestionar todas las solicitudes de tRPC mediante esta única ruta que captura cualquier solicitud.

Pase el router, la función createContext y los objetos de solicitud y respuesta a fetchRequestHandler.

Cree un archivo utils/trpc.ts. Llame a createTRPCReact() para crear el objeto de cliente trpc con tipos. Este objeto tiene una propiedad por cada procedimiento de su router y cada una expone hooks de React Query.

La importación del tipo AppRouter procede de su archivo del servidor; TypeScript sigue la cadena de importaciones para validar todos los usos.

En el layout de su aplicación o en _app.tsx, cree una instancia de QueryClient y una instancia del cliente de tRPC mediante trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] }).

Envuelva el árbol de componentes en trpc.Provider (con el cliente de trpc) y QueryClientProvider (con QueryClient). Ambos proveedores son necesarios.

En cualquier componente: const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' }). El hook tiene tipos completos: data es el tipo de retorno inferido del procedimiento hello y el objeto de entrada se comprueba según el esquema de Zod.

Pasar un tipo de entrada incorrecto provoca un error de compilación de TypeScript, no un error en tiempo de ejecución.

Para que tRPC funcione, el cliente debe poder importar tipos desde el archivo del servidor. En un proyecto de Next.js, el código del servidor y del cliente comparte la misma compilación de TypeScript, por lo que las importaciones funcionan directamente.

En un monorepo con paquetes separados, configure referencias de proyectos de TypeScript o alias de rutas en tsconfig.json para apuntar al paquete del servidor.

El handler de tRPC se ejecuta en el servidor (como una ruta de API de Next.js o una Edge Function). El cliente de tRPC se ejecuta en el navegador. TypeScript evalúa las importaciones de tipos durante la compilación sin ejecutar código del servidor en el navegador.

En el cliente solo se importa el tipo AppRouter, no la implementación real, por lo que ningún secreto del servidor se filtra al bundle del cliente.

Inicie el servidor de desarrollo de Next.js y abra la consola del navegador. La llamada trpc.hello.useQuery debe registrar la respuesta del servidor. Consulte la pestaña Network para ver la solicitud HTTP a /api/trpc/hello, con la entrada agrupada como parámetro de consulta.

De forma predeterminada, httpBatchLink combina varias solicitudes simultáneas en una sola llamada HTTP, algo visible en la cascada de red.

¿Qué función inicializa la instancia de tRPC y proporciona las fábricas de routers y procedimientos?

Instale @trpc/server, @trpc/client, @trpc/react-query y @tanstack/react-query. Inicialice tRPC con initTRPC.create(), defina los procedimientos y exporte el tipo AppRouter. Cree la ruta de API catch-all de Next.js, configure TRPCProvider y QueryClientProvider y, después, llame a los procedimientos con trpc.procedureName.useQuery().

TypeScript impone todo el contrato entre el cliente y el servidor durante la compilación, sin generar código.