El problema que resuelve tRPC

Al crear una API REST en TypeScript, el servidor define la forma de la respuesta. El cliente debe crear manualmente los tipos de TypeScript correspondientes. Con el tiempo, estos tipos divergen a medida que evoluciona la API, y el compilador no puede detectar la discrepancia porque los tipos están definidos en paquetes independientes.

Un campo cuyo nombre se cambia en el servidor se convierte en un error silencioso en tiempo de ejecución en el cliente.

GraphQL resuelve la divergencia de tipos al generar tipos de TypeScript a partir del esquema mediante herramientas como graphql-codegen. Este enfoque funciona bien, pero añade complejidad: un lenguaje de consulta independiente (GraphQL SDL), un paso de generación de código en la canalización de compilación y herramientas para gestionar el esquema.

Para los equipos que ya utilizan GraphQL, codegen es la respuesta adecuada. Para los equipos que quieren seguridad de tipos sin la sobrecarga de GraphQL, tRPC ofrece una alternativa.

El enfoque de tRPC destaca por su sencillez: defina los procedimientos de la API en el servidor como funciones de TypeScript, exporte el tipo del router e importe ese tipo en el cliente. No se necesita generación de código ni un lenguaje de esquemas independiente.

El propio compilador de TypeScript aplica el contrato entre el cliente y el servidor durante la compilación.

tRPC requiere que el servidor y el cliente compartan tipos mediante importaciones de TypeScript. Esto funciona de forma natural en un monorepo (Turborepo, Nx, pnpm workspaces), donde el servidor y el cliente son paquetes independientes que pueden importarse entre sí.

En un backend y un frontend completamente independientes, tendría que publicar los tipos del router como un paquete compartido. Esto añade un paso de publicación, pero sigue sin requerir generación de código.

En el servidor, defina un router y exporte su tipo: export type AppRouter = typeof appRouter. En el cliente, importe ese tipo y cree un cliente tipado: createTRPCReact(). El cliente sabe exactamente qué procedimientos existen y cuáles son sus tipos de entrada y salida.

Si cambia el nombre de un procedimiento en el servidor, TypeScript muestra inmediatamente un error en el cliente.

Como tRPC utiliza directamente el sistema de tipos de TypeScript, el editor proporciona autocompletado completo para los nombres de los procedimientos, las formas de entrada y los tipos de retorno en el cliente. Cambiar el nombre de un procedimiento es una refactorización de cambio de nombre de TypeScript, no una búsqueda y sustitución manual en todo el código.

En la práctica, esta mejora de la experiencia de desarrollo es la función más valorada de tRPC.

De forma predeterminada, tRPC utiliza HTTP como transporte. Cada llamada a un procedimiento es una solicitud HTTP. tRPC también admite WebSockets para las suscripciones. El transporte es un detalle de implementación; la API del cliente es idéntica independientemente del transporte.

También puede exponer los procedimientos de tRPC como endpoints REST convencionales mediante el adaptador REST, para mantener la compatibilidad con clientes que no utilizan tRPC.

tRPC funciona como middleware en Express, Fastify y Hono. En Next.js, se integra mediante controladores de rutas de API. El iniciador create-t3-app (T3 Stack) combina tRPC, Prisma, NextAuth y Tailwind en una plantilla de Next.js full-stack.

T3 Stack es el punto de partida más popular para tRPC y demuestra patrones preparados para producción.

Otro enfoque REST con seguridad de tipos consiste en definir esquemas de Zod, generar automáticamente una especificación de OpenAPI y generar tipos de TypeScript a partir de ella. Esto proporciona un contrato de API que pueden consumir clientes que no estén escritos en TypeScript.

tRPC es más sencillo, pero solo funciona con TypeScript. OpenAPI+Zod añade complejidad, pero produce un contrato de API público. Elija tRPC para la comunicación interna entre TypeScript y TypeScript; elija OpenAPI para las API públicas.

tRPC no sustituye a REST cuando necesita una API pública consumida por terceros, clientes móviles que no estén escritos en TypeScript o socios que necesiten un contrato estable y versionado. Está pensado específicamente para monorepos de TypeScript que requieren seguridad de tipos de extremo a extremo.

Comprender este alcance evita adoptar tRPC en contextos en los que REST o GraphQL se adapten mejor.

Al ejecutar npm create t3-app@latest, se crea la estructura inicial de un proyecto de Next.js con tRPC, Prisma, NextAuth.js, Tailwind CSS y TypeScript preconfigurados. El código generado muestra la estructura del router, la creación del contexto y la configuración del cliente.

Estudiar esta estructura inicial es la forma más rápida de comprender cómo encajan todas las piezas de tRPC en una aplicación real.

¿Cómo comparte tRPC los tipos entre el servidor y el cliente sin generar código?

tRPC resuelve la divergencia de tipos entre el cliente y el servidor de TypeScript al compartir directamente mediante una importación el tipo TypeScript del router, eliminando la generación de código. Funciona en monorepos y se integra con Next.js, Express, Fastify y Hono. T3 Stack (create-t3-app) es la plantilla inicial estándar para producción.

tRPC es exclusivo de TypeScript y es más adecuado para aplicaciones internas full-stack que para API públicas.