trpc-patterns

TRPC Patterns Overview Implement TRPC routers following the project's established patterns for schema definition, custom procedures, middleware, and error handling. When to Use This Skill Use this skill when: Creating new TRPC routers Adding procedures to existing routers Building custom middleware for authorization Implementing error handling in TRPC endpoints Need examples of proper TRPC patterns Core Patterns 1. Simple Inline Schemas For simple validation schemas, define them inline within the procedure. Always use types from @project/common instead of hardcoding values. Pattern: import { OrganizationRoles } from "@project/common" ; import { z } from "zod" ; export const router = { createInvitation : protectedProcedure . input ( z . object ( { email : z . string ( ) . email ( ) , organizationId : z . string ( ) . min ( 1 ) , role : z . enum ( [ OrganizationRoles . Owner , OrganizationRoles . Admin , OrganizationRoles . Member ] ) , } ) , ) . mutation ( async ( { ctx , input } ) => { // Implementation } ) , } satisfies TRPCRouterRecord ; Rules: ✅ Inline simple schemas directly in procedure definition ✅ Use enum values from @project/common ❌ Don't create separate schema constants for simple cases ❌ Don't hardcode enum values like ["owner", "admin", "member"] See references/simple-schemas.md for more examples. 2. Custom Procedures for Organization Access For organization-scoped operations, use protectedMemberAccessProcedure instead of manually checking membership. Pattern: export const router = { getOrganizationCredentials : protectedMemberAccessProcedure . input ( z . object ( { organizationId : z . string ( ) } ) ) . query ( async ( { ctx , input } ) => { // Organization membership already validated const credentials = await ctx . db . select ( ) . from ( credentialsTable ) ; // Direct implementation } ) , } satisfies TRPCRouterRecord ; Available Procedures: publicProcedure - No authentication required protectedProcedure - Requires authenticated user adminProcedure - Requires admin role protectedMemberAccessProcedure - Requires organization membership Rules: ✅ Use protectedMemberAccessProcedure for org-scoped operations ❌ Don't manually check organization membership in procedures See references/custom-procedures.md for detailed examples and context enhancement patterns. 3. Creating Custom Middleware Build reusable base procedures using the .use() method for middleware logic. Pattern: export const protectedMemberAccessProcedure = protectedProcedure . input ( z . object ( { organizationId : z . string ( ) . min ( 1 ) } ) ) . use ( async function isMemberOfOrganization ( opts ) { const { ctx , input } = opts ; const memberAccess = await ctx . db . select ( ) . from ( membersTable ) . where ( and ( eq ( membersTable . organizationId , input . organizationId ) , eq ( membersTable . userId , ctx . session . user . id ) , ) , ) . limit ( 1 ) ; if ( ! memberAccess . length ) { throw new TRPCError ( { code : "FORBIDDEN" , message : "You are not a member of this organization" , } ) ; } return opts . next ( { ctx : { member : memberAccess [ 0 ] , } , } ) ; } ) ; Middleware Rules: ✅ Use .use() method to chain middleware functions ✅ Always return opts.next() with enhanced context ✅ Name middleware functions descriptively ✅ Build on existing base procedures ❌ Don't create utility function approaches See references/middleware-patterns.md for advanced middleware examples. 4. Error Handling Always use standardized error helpers from @/infrastructure/errors.ts . Pattern: import { badRequestError , unauthorizedError , forbiddenError , notFoundError , } from "@/infrastructure/errors" ; export const router = { deleteProject : protectedProcedure . input ( z . object ( { projectId : z . string ( ) } ) ) . mutation ( async ( { ctx , input } ) => { const project = await ctx . db . select ( ) . from ( projectsTable ) . where ( eq ( projectsTable . id , input . projectId ) ) . limit ( 1 ) ; if ( ! project . length ) { throw notFoundError ( "Project not found" ) ; } if ( project [ 0 ] . ownerId !== ctx . session . user . id ) { throw forbiddenError ( "You don't have permission to delete this project" ) ; } // Implementation... } ) , } satisfies TRPCRouterRecord ; Available Error Helpers: badRequestError(message) - Invalid input or request unauthorizedError(message) - Authentication issues forbiddenError(message) - Authorization/permission issues notFoundError(message) - Missing resources Rules: ✅ Use error helper functions ❌ Don't create TRPCError manually See references/error-handling.md for comprehensive error handling patterns. Type Inference IMPORTANT: TRPC types are automatically inferred from backend router definitions through TypeScript's static type system. No code generation is needed. Pattern: // Backend: apps/web-app/src/projects/trpc/project.ts export const router = { estimateProjectCreation : protectedProcedure . input ( z . object ( { organizationId : z . string ( ) } ) ) . query ( async ( { ctx , input } ) => { return { integrationsCount : 10 , estimatedSeconds : 5 , } ; } ) , } satisfies TRPCRouterRecord ; // Frontend: Types are automatically inferred via static imports const estimate = trpc . project . estimateProjectCreation . useQuery ( { organizationId : "123" , } ) ; // TypeScript knows estimate.data has { integrationsCount: number, estimatedSeconds: number } Type Inference Rules: ✅ Types are statically inferred from backend router through TypeScript imports ✅ Frontend imports AppRouter type and gets full type safety ✅ Server does NOT need to be running for type inference (it's static analysis) ✅ Changes to backend router immediately update frontend types on next TypeScript check ❌ Don't create manual type definitions for TRPC endpoints ❌ Don't expect runtime type generation - it's compile-time only How It Works: Backend exports AppRouter type from root router Frontend imports AppRouter and creates typed TRPC client TypeScript compiler statically analyzes backend code and infers all types IDE and type checker see changes immediately after file save If new endpoint doesn't appear: Check if backend router is properly exported in root router Verify TypeScript can resolve the import path Restart TypeScript language server in IDE if needed SQL Query Optimization Always prefer single SQL queries with JOINs over multiple separate queries. Pattern: // ✅ Good - Single optimized query with joins export const router = { getOrganizationsDetails : protectedProcedure . query ( async ( { ctx : { session , db } } ) => { const result = await db . select ( { organization : organizationsTable , project : projectsTable , integration : organizationIntegrationsTable , userRole : membersTable . role , } ) . from ( membersTable ) . innerJoin ( organizationsTable , eq ( membersTable . organizationId , organizationsTable . id ) ) . leftJoin ( projectsTable , eq ( projectsTable . organizationId , organizationsTable . id ) ) . where ( eq ( membersTable . userId , session . user . id ) ) ; return groupResults ( result ) ; } ) , } ; SQL Optimization Rules: Use single queries with JOINs instead of multiple queries Only fetch data that's actually needed Use LEFT JOIN for optional relationships, INNER JOIN for required Group/aggregate in SQL when possible, otherwise in application code Resources references/ Detailed reference documentation for each pattern: simple-schemas.md - Complete examples of inline schema patterns custom-procedures.md - Available procedures and context enhancement middleware-patterns.md - Advanced middleware creation patterns error-handling.md - Comprehensive error handling guide