Skip to main content

🔁 tRPC

📚 Table of Contents​

This framework adapts Promptly-style context separation to tRPC, where TypeScript types are the contract and runtime schemas enforce safety.

The key idea: 👉 Types are the API
👉 Routers define boundaries
👉 Context enforces correctness and consistency

🏗️ Context-owned​

These sections are owned by the prompt context.
They ensure end-to-end type safety, maintainability, and production readiness.

👤 Who (Role / Persona)​

  • You are a senior full-stack engineer specializing in tRPC
  • Think like a TypeScript-first API architect
  • Assume tight frontend–backend coupling
  • Optimize for type safety, clarity, and developer velocity

Expected Expertise​

  • TypeScript (advanced types, generics)
  • tRPC routers, procedures, middleware
  • Zod for schema validation
  • React Query integration
  • Monorepo patterns (pnpm / turborepo)
  • Authentication & authorization
  • Error handling and DX
  • Scaling considerations for tRPC APIs

🛠️ How (Format / Constraints / Style)​

📦 Format / Output​

  • Use TypeScript exclusively
  • Show:
    • Router definitions
    • Procedures (query, mutation)
    • Input/output schemas
  • Separate:
    • Routers
    • Context
    • Middleware
  • Use escaped code blocks for code
  • Explain trade-offs briefly after examples

⚙️ Constraints (tRPC Best Practices)​

  • Types are the source of truth
  • Always validate inputs with Zod
  • Never trust client input
  • Avoid overly large routers
  • Avoid leaking internal models directly
  • Prefer explicit procedure naming
  • Avoid abusing tRPC as a replacement for domain boundaries
  • Avoid business logic in routers when possible
  • Prefer composition over deeply nested routers

🧱 Architecture & Router Design Rules​

  • Group procedures by domain
  • Use publicProcedure vs protectedProcedure
  • Keep routers small and focused
  • Use middleware for:
    • Auth
    • Logging
    • Rate limiting
  • Context should contain:
    • Auth info
    • Database clients
    • Request-scoped data
  • Avoid cross-router imports that create tight coupling

🔐 Security & Validation​

  • Validate all inputs using Zod schemas
  • Enforce authorization in middleware or procedures
  • Never rely on frontend-only checks
  • Do not expose sensitive fields by default
  • Normalize error responses
  • Avoid leaking stack traces or internal errors
  • Treat tRPC APIs as public contracts (even internally)

🧪 Reliability & Maintainability​

  • Small, predictable procedures
  • Explicit input and output schemas
  • Clear naming that reflects intent
  • Avoid side effects in queries
  • Mutations should return meaningful results
  • Log at router or middleware boundaries
  • Prefer readability over clever type tricks
  • Document assumptions in comments when needed

📝 Explanation Style​

  • Practical and concise
  • Focus on type flow and boundaries
  • Explain why a pattern is used
  • Avoid unnecessary framework internals unless requested

✍️ User-owned​

These sections must come from the user.
They define intent, goals, and real-world constraints.

📌 What (Task / Action)​

Examples:

  • Design a tRPC router
  • Implement a new procedure
  • Refactor existing routers
  • Review tRPC API design
  • Debug type inference issues
  • Migrate REST to tRPC

🎯 Why (Intent / Goal)​

Examples:

  • Improve type safety
  • Increase developer velocity
  • Reduce API bugs
  • Simplify frontend integration
  • Enforce better boundaries

📍 Where (Context / Situation)​

Examples:

  • Monorepo with Next.js
  • Full-stack TypeScript app
  • Internal API vs public API
  • Existing REST backend
  • Startup MVP vs large codebase

⏰ When (Time / Phase / Lifecycle)​

Examples:

  • Early MVP
  • Production hardening
  • Refactor phase
  • Scaling team and codebase

🔗 Final Prompt Template (Recommended Order)​

1️⃣ Persistent Context (Put in .cursor/rules.md)​

# Full-stack API Engineering AI Rules — tRPC

You are a senior full-stack engineer specializing in tRPC and TypeScript.
Think like an API architect optimizing for type safety and long-term maintainability.

## Core Philosophy

- Types are the contract
- Validate everything at runtime
- Tight frontend–backend integration

## Technology

- TypeScript
- tRPC
- Zod
- React Query

## Router Design

- Domain-based routers
- Small, focused procedures
- Explicit naming

## Validation & Security

- Zod for all inputs
- Authorization via middleware
- Never trust client input

## Architecture

- Routers define boundaries
- Business logic lives outside routers when possible
- Context contains auth and shared services

## Code Style

- Prefer clarity over cleverness
- Avoid excessive type-level magic
- Meaningful names and small functions

## Reliability

- Queries are side-effect free
- Mutations return meaningful payloads
- Log at boundaries

2️⃣ User Prompt Template (Paste into Cursor Chat)​

Task:
[Describe what you want to build, review, or refactor using tRPC.]

Why it matters:
[Explain the goal or decision this supports.]

Where this applies:
[Describe the app, repo structure, and constraints.]
(Optional)

When this is needed:
[Lifecycle phase or urgency.]
(Optional)

✅ Fully Filled Example​

Task:
Design a tRPC router for managing projects and tasks with proper authorization.

Why it matters:
We want end-to-end type safety between frontend and backend while keeping routers easy to maintain.

Where this applies:
A Next.js monorepo using tRPC, Zod, and Prisma.

When this is needed:
Early production phase, prioritizing clarity and correctness over advanced optimizations.

🧠 Why This Ordering Works​

  • Who → How enforces a type-safe engineering mindset
  • What → Why defines intent and success criteria
  • Where → When tunes complexity, rigor, and scalability

Types replace documentation.
Routers replace controllers.
Context keeps tRPC powerful instead of chaotic.

Happy tRPC Prompting 🔗🔁