tRPC Conventions

trpctypescriptfullstack

Conventions for building end-to-end type-safe APIs with tRPC v11, covering router structure, procedures, context, middleware, and client integration with React Query.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

# tRPC Conventions ## Router Structure - Define the root router in `server/trpc/root.ts`. Merge sub-routers per feature domain. - Each feature has its own router file: `server/trpc/routers/users.ts`, `server/trpc/routers/orders.ts`. - Name routers by their resource noun: `usersRouter`, `ordersRouter`, `authRouter`. - Export the `AppRouter` type from `root.ts` for client consumption. Never export the actual router implementation to the client bundle. ## tRPC Initialization - Initialize tRPC once in `server/trpc/trpc.ts`: `const t = initTRPC.context<Context>().create()`. - Export `publicProcedure`, `protectedProcedure`, and `router` from this file — do not export `t` directly. - Add a `superjson` transformer for Date, Map, Set serialization support. - Enable error formatting to include Zod validation details in development only. ## Context - Define `Context` type in `server/trpc/context.ts`. Include `session`, `db`, and any request-scoped data. - Create context in `createContext()` function passed to the adapter — pull auth session, DB connection here. - Keep context creation fast — avoid slow I/O in `createContext`. Lazy-load expensive resources in middleware instead. ## Procedures - Use `query` for read operations (idempotent, cacheable). Use `mutation` for state changes. - Always define `input` schema with Zod for every procedure that accepts input. - Always define an explicit `output` schema for public-facing procedures — prevents accidental data leakage. - Return plain objects or Zod-validated shapes — never return ORM entities with circular references. ## Protected Procedures - Create `protectedProcedure` by extending `publicProcedure` with auth middleware. - Auth middleware: check `ctx.session`, throw `TRPCError({ code: 'UNAUTHORIZED' })` if absent. - Create role-based procedures: `adminProcedure`, `moderatorProcedure` extending `protectedProcedure`. - Access the user in protected procedures via `ctx.session.user` — always typed, never nullable after auth check. ## Error Handling - Throw `TRPCError` with appropriate codes: `NOT_FOUND`, `UNAUTHORIZED`, `FORBIDDEN`, `BAD_REQUEST`, `INTERNAL_SERVER_ERROR`. - Include a descriptive `message` and optional `cause` for internal debugging. - Use `errorFormatter` to strip sensitive error details in production — expose cause only in development. - Never throw plain `Error` in procedures — always use `TRPCError` for consistent client handling. ## Input Validation - Use Zod for all inputs. Define schemas adjacent to the procedure or in a `schemas/` file. - Use `.transform()` for input normalization (trim strings, lowercase emails) — keep handler logic clean. - For complex mutations, use discriminated unions to handle multiple operation types in one procedure. - Apply `.min()`, `.max()`, `.email()`, `.url()` constraints directly on Zod schemas — not in procedure logic. ## Client Integration - Use `@trpc/react-query` for React clients. Call `createTRPCReact<AppRouter>()` once in `lib/trpc.ts`. - Use `trpc.users.getById.useQuery(id)` for queries, `trpc.orders.create.useMutation()` for mutations. - Invalidate related queries after mutations: `utils.users.list.invalidate()` in `onSuccess`. - Prefetch critical data in server components using `createServerSideHelpers` for SSR/SSG. ## Performance - Use `httpBatchLink` in production to batch multiple procedure calls into a single HTTP request. - Use `splitLink` to separate queries (batched HTTP) from subscriptions (WebSocket). - Enable request deduplication for queries with the same input that fire simultaneously. ## Anti-Patterns - Do not use REST endpoints alongside tRPC for the same resources — pick one pattern. - Do not skip Zod `output` schemas for procedures that return sensitive models. - Do not call tRPC procedures from other procedures — use shared service functions instead. - Do not define router logic inside Next.js page or layout files.

CLI

npx mindaxis apply trpc-rules --target cursor --scope project

Используется в паках

Frontend Build Tooling

Vite, Webpack, Turbo, and modern frontend build pipeline setup

Открыть пак →

← Правила