tRPC - End-to-End Type Safety

progressive_disclosure: entry_point: summary sections: - id: summary title: "tRPC Overview" tokens: 70 next: [when_to_use, quick_start] - id: when_to_use title: "When to Use tRPC" tokens: 150 next: [quick_start, core_concepts] - id: quick_start title: "Quick Start" tokens: 300 next: [core_concepts, router_definition] - id: core_concepts title: "Core Concepts" tokens: 400 next: [router_definition, procedures] - id: router_definition title: "Router Definition" tokens: 350 next: [procedures, context] - id: procedures title: "Procedures (Query & Mutation)" tokens: 400 next: [input_validation, context] - id: input_validation title: "Input Validation with Zod" tokens: 350 next: [context, middleware] - id: context title: "Context Management" tokens: 400 next: [middleware, error_handling] - id: middleware title: "Middleware" tokens: 400 next: [error_handling, client_setup] - id: error_handling title: "Error Handling" tokens: 350 next: [client_setup, react_integration] - id: client_setup title: "Client Setup" tokens: 400 next: [react_integration, nextjs_integration] - id: react_integration title: "React Query Integration" tokens: 450 next: [nextjs_integration, subscriptions] - id: nextjs_integration title: "Next.js App Router Integration" tokens: 500 next: [subscriptions, file_uploads] - id: subscriptions title: "Real-time Subscriptions" tokens: 400 next: [file_uploads, batching] - id: file_uploads title: "File Uploads" tokens: 300 next: [batching, typescript_inference] - id: batching title: "Batch Requests & Data Loaders" tokens: 350 next: [typescript_inference, testing] - id: typescript_inference title: "TypeScript Inference Patterns" tokens: 300 next: [testing, production_patterns] - id: testing title: "Testing Strategies" tokens: 400 next: [production_patterns, comparison] - id: production_patterns title: "Production Patterns" tokens: 450 next: [comparison, migration] - id: comparison title: "Comparison with REST & GraphQL" tokens: 250 next: [migration, best_practices] - id: migration title: "Migration from REST" tokens: 300 next: [best_practices] - id: best_practices title: "Best Practices & Performance" tokens: 400

Summary

tRPC enables end-to-end type safety between TypeScript clients and servers without code generation. Define your API once, get automatic type inference everywhere.

Key Benefits: Zero codegen, TypeScript inference, React Query integration, minimal boilerplate.

When to Use tRPC

✅ Perfect For:

• Full-stack TypeScript applications (Next.js, T3 stack)
• Projects where client and server share TypeScript codebase
• Teams wanting REST-like simplicity with GraphQL-like type safety
• Apps using React Query for data fetching
• Internal APIs where you control both client and server

❌ Avoid When:

• Public APIs consumed by non-TypeScript clients
• Microservices in different languages
• Mobile apps using Swift/Kotlin (use REST/GraphQL instead)
• Need API documentation for external developers (OpenAPI better)

When to Choose:

• tRPC: Full-stack TypeScript, monorepo, internal tools
• REST: Public APIs, language-agnostic, broad compatibility
• GraphQL: Complex data graphs, multiple clients, flexible queries

Quick Start

Installation

# Server dependencies
npm install @trpc/server zod

# React/Next.js client dependencies
npm install @trpc/client @trpc/react-query @tanstack/react-query

Define Router (Server)

// server/trpc.ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';

const t = initTRPC.create();

export const appRouter = t.router({
  hello: t.procedure
    .input(z.object({ name: z.string() }))
    .query(({ input }) => {
      return { greeting: `Hello ${input.name}` };
    }),

  createPost: t.procedure
    .input(z.object({ title: z.string(), content: z.string() }))
    .mutation(async ({ input }) => {
      // Save to database
      return { id: 1, ...input };
    }),
});

export type AppRouter = typeof appRouter;

Use in Client (React)

// client/trpc.ts
import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '../server/trpc';

export const trpc = createTRPCReact<AppRouter>();

// Component
function MyComponent() {
  const { data } = trpc.hello.useQuery({ name: 'World' });
  const createPost = trpc.createPost.useMutation();

  return <div>{data?.greeting}</div>; // Fully typed!
}

Next: Learn core concepts or dive into router definition.

Core Concepts

The tRPC Philosophy

tRPC provides type-safe remote procedure calls by sharing TypeScript types between client and server. No code generation—just TypeScript's inference.

Key Components

1. Router: Collection of procedures (API endpoints)
2. Procedure: Single API operation (query or mutation)
3. Context: Request-scoped data (user, database, etc.)
4. Middleware: Intercept/modify requests (auth, logging)
5. Input/Output: Validated with Zod schemas

Type Flow

// Server defines types
const router = t.router({
  getUser: t.procedure
    .input(z.string())
    .query(({ input }) => ({ id: input, name: 'Alice' })),
});

// Client gets automatic types
const user = await trpc.getUser.query('123');
// user is typed as { id: string, name: string }

Architecture Pattern

┌─────────────┐     Type-safe     ┌──────────────┐
│   Client    │ ←────────────────→ │    Server    │
│ (React)     │   No codegen!      │   (Node.js)  │
└─────────────┘                    └──────────────┘
      ↓                                    ↓
 React Query                          tRPC Router
 (caching)                            (procedures)

Advantages:

• Changes propagate instantly (no build step)
• Rename refactoring works across client/server
• Impossible to call wrong types
• Auto-complete for all API methods

Router Definition

Basic Router Structure

import { initTRPC } from '@trpc/server';

const t = initTRPC.create();

export const appRouter = t.router({
  // Procedures go here
});

export type AppRouter = typeof appRouter;

Nested Routers (Namespacing)

const userRouter = t.router({
  getById: t.procedure
    .input(z.string())
    .query(({ input }) => getUser(input)),

  create: t.procedure
    .input(z.object({ name: z.string(), email: z.string() }))
    .mutation(({ input }) => createUser(input)),
});

const postRouter = t.router({
  list: t.procedure.query(() => getPosts()),
  create: t.procedure
    .input
how to use trpc-type-safety
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use trpc-type-safety on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add trpc-type-safety
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/bobmatnyc/claude-mpm-skills --skill trpc-type-safetycopy
The skills CLI fetches trpc-type-safety from GitHub repository bobmatnyc/claude-mpm-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/trpc-type-safety
Reload or restart Cursor to activate trpc-type-safety. Access the skill through slash commands (e.g., /trpc-type-safety) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?