web-trpc-api

author	dotagents
name	web-trpc-api
description	tRPC procedures with auth context, Zod inputs, query vs mutation semantics, Prisma on server, error mapping, and optional Next.js REST route handlers that share validation. For T3 Next.js apps. Triggers on tRPC, router, procedure, protectedProcedure, prisma, zod, app/api route.ts.

Web tRPC and API

Use with typescript-web spec and web-trpc-api Cursor rule. general-typescript covers Bun and language hygiene.

Principles

1. Context first: build tRPC context from the incoming request (session, user id, tenant). Every procedure that touches user-owned data reads auth from context, not from client-supplied “current user id” alone.
2. Zod at the edge: .input(z.object(...)) (and .output when the team enforces it). Share input schemas with forms or URL parsers when the same shape appears in multiple places.
3. Query vs mutation: queries for reads (repeatable, no lasting writes). mutations for writes. Name procedures so intent is obvious (listX, getById, createX, updateX, deleteX).
4. Authorization: authenticate, then authorize per resource (row-level, tenant, role). Reject with FORBIDDEN or NOT_FOUND (when hiding existence) per product policy.
5. Errors: map domain failures to tRPC codes; log server details without sending them to the client.
6. REST coexistence: if route.ts exposes HTTP for the same domain, reuse Zod + domain functions; keep GET read-only and align status codes (401/403/404/422) with your HTTP helper conventions.

Reference index

Topic	File
Procedures, context, auth patterns	reference-procedures-auth.md
REST bridge, HTTP semantics	reference-rest-bridge.md

Delegation

• URL-only concerns: web-url-search-state.
• HeroUI / TSX: heroui-components.
• Pure TypeScript types: typescript-types.