TypeScript Academy · Lesson

The tRPC Architecture

How tRPC eliminates API schema duplication.

The tRPC Architecture is a free TypeScript Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the TypeScript Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The End-to-End Problem

In a typical web app, the server defines an API and the client calls it. Keeping their types in sync is hard: change a field on the server and the client silently breaks at runtime. tRPC solves this by sharing types directly, with no code generation.

// Server: returns { id: number; name: string }
// Client: must know that shape exactly
// Without sync: runtime errors when they drift

What tRPC Is

tRPC is a library for building fully typed APIs in TypeScript. The server defines procedures; the client calls them as if they were local functions, with complete autocomplete and type checking inferred from the server code.

// Client call looks like a local function:
// const user = await client.user.byId.query(1);
// user is typed automatically from the server

No Codegen

Unlike GraphQL or OpenAPI workflows, tRPC needs no code generation step. There is no schema file to compile and no generated client. Types flow from server to client purely through TypeScript inference at compile time.

// No .graphql files, no generated SDK
// Just import a type from the server package

The Router Is the Contract

The center of tRPC is the router. It is a tree of procedures (queries and mutations). The router object on the server, and specifically its inferred type, is the single source of truth shared with the client.

// appRouter (server) defines every procedure
// type AppRouter = typeof appRouter is the contract

How Types Are Shared

The server exports only the type of its router, not the implementation. The client imports that type and uses it to type a proxy client. No server code ships to the browser; only types, which are erased at build time.

// server.ts
export type AppRouter = typeof appRouter;

// client.ts
import type { AppRouter } from '../server';

Queries and Mutations

Procedures come in two main kinds. A query reads data and is typically idempotent. A mutation changes data. The distinction maps to caching and HTTP semantics and shapes how the client calls them.

// client.user.list.query()      -> read
// client.user.create.mutate(...) -> write

Runtime vs Types

tRPC has two layers. At runtime, calls are JSON over HTTP, handled by an adapter. At compile time, the shared AppRouter type makes every call fully checked. The runtime is thin; the type safety is the value.

// Runtime: POST /trpc/user.byId  body: {"input":1}
// Types: client.user.byId.query(1) is checked end to end

Why Inference Beats Codegen

Because types are inferred, there is no sync step to forget. Edit a procedure and the client immediately reflects the change with red squiggles where calls no longer match. The feedback is instant and lives in your editor.

// Add a required input field on the server
// -> every client call missing it becomes a type error

Where tRPC Fits

tRPC shines in full-stack TypeScript monorepos where client and server share a codebase, such as Next.js apps. It is not for public APIs consumed by other languages; for those you still want a language-agnostic schema like OpenAPI or GraphQL.

// Great: Next.js app, shared types, internal API
// Not ideal: public API for non-TS consumers

The Big Picture

The flow is: define procedures on a router, export the router type, attach an HTTP adapter, and create a typed client from that type. Every call is checked against the server contract with zero generated code. The next lessons build each piece.

// Roadmap:
// 1. initTRPC + procedures + appRouter
// 2. export AppRouter, create typed client
// 3. context + middleware for auth

Trust the Compiler

The mindset shift: the API contract lives in types, enforced by the compiler, not in documentation or runtime validation alone. If it compiles, client and server agree. That guarantee is what "end-to-end type safety" means.

// If client.ts compiles, it matches the current server.

Quick Check

Test your understanding of the tRPC architecture.

Recap

You learned the tRPC model.

The router is the contract; its type is the single source of truth.
The server exports only the AppRouter type, not code.
Queries read, mutations write; runtime is JSON over HTTP.
Type safety comes from inference, with no codegen step.

Next: defining routers and procedures.

Frequently asked questions

Is the “The tRPC Architecture” lesson free?

Yes — the full text of “The tRPC Architecture” is free to read here on the web, and the TypeScript Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the TypeScript Academy course, upgrade to CoddyKit PRO.

What will I learn in “The tRPC Architecture”?

How tRPC eliminates API schema duplication. You practise TypeScript Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start TypeScript Academy?

No prior experience is required. TypeScript Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “The tRPC Architecture” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this TypeScript Academy lesson?

Yes. Every TypeScript Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to TypeScript Academy