La arquitectura de tRPC
Descubra cómo tRPC elimina la duplicación de esquemas de API.
La arquitectura de tRPC es una lección gratuita de TypeScript Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de TypeScript Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de TypeScript Academy incluye 4 lecciones en total.
El problema integral
En una aplicación web típica, el servidor define una API y el cliente la utiliza. Mantener sus tipos sincronizados es difícil: si cambia un campo en el servidor, el cliente falla silenciosamente en tiempo de ejecución. tRPC resuelve esto compartiendo los tipos directamente, sin generación de código.
// Server: returns { id: number; name: string }
// Client: must know that shape exactly
// Without sync: runtime errors when they driftQué es tRPC
tRPC es una biblioteca para crear APIs completamente tipadas en TypeScript. El servidor define procedimientos; el cliente los utiliza como si fueran funciones locales, con autocompletado completo y comprobación de tipos inferida a partir del código del servidor.
// Client call looks like a local function:
// const user = await client.user.byId.query(1);
// user is typed automatically from the serverSin generación de código
A diferencia de los flujos de trabajo de GraphQL u OpenAPI, tRPC no necesita ningún paso de generación de código. No hay ningún archivo de esquema que compilar ni ningún cliente generado. Los tipos fluyen del servidor al cliente únicamente mediante la inferencia de TypeScript en tiempo de compilación.
// No .graphql files, no generated SDK
// Just import a type from the server packageEl router es el contrato
El centro de tRPC es el router. Es un árbol de procedimientos (consultas y mutaciones). El objeto router del servidor y, concretamente, su tipo inferido, es la única fuente de verdad que se comparte con el cliente.
// appRouter (server) defines every procedure
// type AppRouter = typeof appRouter is the contractCómo se comparten los tipos
El servidor exporta únicamente el tipo de su router, no la implementación. El cliente importa ese tipo y lo utiliza para tipar un cliente proxy. Ningún código del servidor se envía al navegador; solo se envían los tipos, que se eliminan durante la compilación.
// server.ts
export type AppRouter = typeof appRouter;
// client.ts
import type { AppRouter } from '../server';Consultas y mutaciones
Los procedimientos son de dos tipos principales. Una consulta lee datos y normalmente es idempotente. Una mutación modifica datos. Esta distinción se relaciona con el almacenamiento en caché y la semántica de HTTP, y determina cómo los invoca el cliente.
// client.user.list.query() -> read
// client.user.create.mutate(...) -> writeTiempo de ejecución frente a tipos
tRPC tiene dos capas. En tiempo de ejecución, las llamadas son solicitudes JSON sobre HTTP gestionadas por un adaptador. En tiempo de compilación, el tipo compartido AppRouter comprueba completamente cada llamada. El tiempo de ejecución es sencillo; el valor está en la seguridad de tipos.
// Runtime: POST /trpc/user.byId body: {"input":1}
// Types: client.user.byId.query(1) is checked end to endPor qué la inferencia supera a la generación de código
Como los tipos se infieren, no hay ningún paso de sincronización que se pueda olvidar. Edite un procedimiento y el cliente reflejará inmediatamente el cambio, mostrando subrayados rojos donde las llamadas ya no coincidan. La retroalimentación es instantánea y aparece en el editor.
// Add a required input field on the server
// -> every client call missing it becomes a type errorDónde encaja tRPC
tRPC destaca en monorepos de TypeScript full-stack donde el cliente y el servidor comparten una base de código, como en las aplicaciones de Next.js. No está pensado para API públicas consumidas por otros lenguajes; para esos casos sigue siendo recomendable un esquema independiente del lenguaje, como OpenAPI o GraphQL.
// Great: Next.js app, shared types, internal API
// Not ideal: public API for non-TS consumersPanorama general
El flujo es el siguiente: definir procedimientos en un router, exportar el tipo del router, conectar un adaptador HTTP y crear un cliente con tipos a partir de ese tipo. Cada llamada se comprueba con respecto al contrato del servidor sin generar código. En las próximas lecciones se creará cada pieza.
// Roadmap:
// 1. initTRPC + procedures + appRouter
// 2. export AppRouter, create typed client
// 3. context + middleware for authConfíe en el compilador
El cambio de mentalidad consiste en que el contrato de la API reside en los tipos, aplicados por el compilador, no únicamente en la documentación o en la validación durante la ejecución. Si compila, el cliente y el servidor coinciden. Eso es lo que significa "seguridad de tipos de extremo a extremo".
// If client.ts compiles, it matches the current server.Comprobación rápida
Compruebe su comprensión de la arquitectura de tRPC.
Resumen
Ha aprendido el modelo de tRPC.
- El router es el contrato; su tipo es la única fuente de verdad.
- El servidor exporta únicamente el tipo
AppRouter, no código. - Las consultas leen y las mutaciones escriben; el tiempo de ejecución utiliza JSON sobre HTTP.
- La seguridad de tipos proviene de la inferencia, sin ningún paso de generación de código.
Siguiente: definir routers y procedimientos.
Preguntas frecuentes
¿La lección «La arquitectura de tRPC» es gratis?
Sí — el texto completo de «La arquitectura de tRPC» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de TypeScript Academy, actualiza a CoddyKit PRO. El curso de TypeScript Academy incluye 4 lecciones en total.
¿Qué aprenderé en «La arquitectura de tRPC»?
Descubra cómo tRPC elimina la duplicación de esquemas de API. Practicas TypeScript Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar TypeScript Academy?
No se requiere experiencia previa. TypeScript Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.
¿Cuánto tiempo toma la lección «La arquitectura de tRPC»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de TypeScript Academy?
Sí. Cada lección de TypeScript Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- La arquitectura de tRPC
- Definición de routers y procedimientos
- Inferencia de tipos entre cliente y servidor
- Middleware y contexto