tRPC para TypeScript: guía completa con ejemplos

¿Qué es tRPC y para qué sirve?

tRPC (TypeScript Remote Procedure Call) es una biblioteca moderna para crear APIs con seguridad de tipos (type-safe) entre el cliente y el servidor. La característica principal de tRPC es que no requiere generación de código ni duplicación de tipos. Simplemente escribes funciones en el servidor y el cliente accede a ellas con soporte completo de TypeScript: autocompletado, verificación de tipos e IntelliSense.

A diferencia de REST o GraphQL, donde necesitas describir manualmente esquemas, endpoints y tipos, tRPC infiere automáticamente los tipos a partir de tu código del servidor. Esto simplifica radicalmente el desarrollo y reduce la cantidad de errores.

Principales ventajas de tRPC:

\n
• Seguridad total de tipos — los errores de tipo se detectan en tiempo de compilación, no en tiempo de ejecución
\n
• Sin generación de código — no es necesario ejecutar generadores ni sincronizar esquemas
\n
• Mínimo boilerplate — menos código que en REST o GraphQL
\n
• Documentación automática — los tipos sirven como documentación
\n
• Simplicidad — funciona como una llamada a función normal
\n

tRPC es ideal para aplicaciones full-stack en TypeScript (Next.js, Remix, Express, Fastify) y para arquitectura de microservicios.

Instalación de tRPC

tRPC consta de varios paquetes. Para el uso básico necesitarás:

# Instalación de las partes del servidor y del cliente\nnpm install @trpc/server @trpc/client\n\n# Instalación del adaptador para React (si usas React)\nnpm install @trpc/react-query @tanstack/react-query\n\n# Instalación del adaptador para Next.js\nnpm install @trpc/next @trpc/react-query @tanstack/react-query\n\n# Instalación de Zod para validación (recomendado)\nnpm install zod

Si usas yarn o pnpm:

yarn add @trpc/server @trpc/client\npnpm add @trpc/server @trpc/client

Para desarrolladores de Python (si usas Python en el backend): tRPC es una biblioteca de TypeScript, pero puedes usarla con Python a través de trpc-py (envoltorio experimental). Sin embargo, el ecosistema principal es TypeScript.

Inicio rápido con ejemplo de código

Vamos a crear una aplicación simple: un servidor con procedimientos para trabajar con usuarios y un cliente que los llama.

1. Servidor (server.ts)

import { initTRPC } from '@trpc/server';\nimport { z } from 'zod';\n\n// Creamos una instancia de tRPC\nconst t = initTRPC.create();\n\n// Definimos el tipo de usuario\ninterface User {\n  id: number;\n  name: string;\n  email: string;\n}\n\n// Base de datos falsa\nconst users: User[] = [\n  { id: 1, name: 'Alice', email: 'alice@example.com' },\n  { id: 2, name: 'Bob', email: 'bob@example.com' },\n];\n\n// Creamos el router con procedimientos\nconst appRouter = t.router({\n  // Procedimiento para obtener todos los usuarios\n  getUsers: t.procedure\n    .query(() => {\n      return users;\n    }),\n\n  // Procedimiento para obtener un usuario por ID\n  getUserById: t.procedure\n    .input(z.number())\n    .query(({ input }) => {\n      return users.find(user => user.id === input) || null;\n    }),\n\n  // Procedimiento para crear un usuario\n  createUser: t.procedure\n    .input(z.object({\n      name: z.string().min(1),\n      email: z.string().email(),\n    }))\n    .mutation(({ input }) => {\n      const newUser: User = {\n        id: users.length + 1,\n        name: input.name,\n        email: input.email,\n      };\n      users.push(newUser);\n      return newUser;\n    }),\n});\n\n// Exportamos el tipo del router para el cliente\nexport type AppRouter = typeof appRouter;

2. Cliente (client.ts)

import { createTRPCClient, httpBatchLink } from '@trpc/client';\nimport type { AppRouter } from './server';\n\n// Creamos el cliente\nconst client