TRPC Router Guide

File Location

• Routers: apps/server/src/routers/lambda/<domain>.ts
• Helpers: apps/server/src/routers/lambda/_helpers/
• Schemas: apps/server/src/routers/lambda/_schema/

Router Structure

Imports

import { TRPCError } from '@trpc/server';
import { z } from 'zod';

import { SomeModel } from '@/database/models/some';
import { authedProcedure, router } from '@/libs/trpc/lambda';
import { serverDatabase } from '@/libs/trpc/lambda/middleware';

Middleware: Inject Models into ctx

Always use middleware to inject models into ctx instead of creating new Model(ctx.serverDB, ctx.userId) inside every procedure.

const domainProcedure = authedProcedure.use(serverDatabase).use(async (opts) => {
  const { ctx } = opts;
  return opts.next({
    ctx: {
      fooModel: new FooModel(ctx.serverDB, ctx.userId),
      barModel: new BarModel(ctx.serverDB, ctx.userId),
    },
  });
});

Then use ctx.fooModel in procedures:

// Good
const model = ctx.fooModel;

// Bad - don't create models inside procedures
const model = new FooModel(ctx.serverDB, ctx.userId);

Exception: When a model needs a different userId (e.g., watchdog iterating over multiple users' tasks), create it inline.

Procedure Pattern

export const fooRouter = router({
  // Query
  find: domainProcedure.input(z.object({ id: z.string() })).query(async ({ input, ctx }) => {
    try {
      const item = await ctx.fooModel.findById(input.id);
      if (!item) throw new TRPCError({ code: 'NOT_FOUND', message: 'Not found' });
      return { data: item, success: true };
    } catch (error) {
      if (error instanceof TRPCError) throw error;
      console.error('[foo:find]', error);
      throw new TRPCError({
        cause: error,
        code: 'INTERNAL_SERVER_ERROR',
        message: 'Failed to find item',
      });
    }
  }),