tRPC: Middleware

tRPC: Middleware

Add cross-cutting logic (auth checks, logging, rate limiting) to procedures via t.middleware

When to Use

• Enforcing authentication on a set of procedures without repeating the check in each handler
• Enriching the context with derived data (user object from session ID) before the handler runs
• Logging request/response for observability across all procedures
• Adding rate limiting or permission checks that apply to procedure groups
• Creating reusable procedure builders (protectedProcedure, adminProcedure)

Instructions

1. Create middleware with t.middleware(async ({ ctx, next }) => { ... }) — call next({ ctx: { ...ctx, ...enriched } }) to pass enriched context to the handler.
2. Attach middleware to a procedure with .use(middleware) — the middleware runs before the input validation and handler.
3. Build typed procedure builders by chaining .use() and exporting the result: export const protectedProcedure = t.procedure.use(isAuthed).
4. Throw new TRPCError({ code: 'UNAUTHORIZED' }) in middleware to reject the request — the error propagates to the client's onError handler.
5. Access the enriched context type in the handler — TypeScript narrows the type based on what middleware adds to ctx.
6. Use .pipe() to compose multiple middleware — each receives the context enriched by the previous middleware.
7. Return next() at the end of middleware — forgetting this causes the procedure to never respond.

// server/trpc.ts — middleware and procedure builders
import { initTRPC, TRPCError } from '@trpc/server';
import type { TRPCContext } from './context';

const t = initTRPC.context<TRPCContext>().create();

// Auth middleware — enriches ctx with session and user
const isAuthed = t.middleware(async ({ ctx, next }) => {
  if (!ctx.session?.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Not signed in' });
  }
  return next({
    ctx: {
      ...ctx,
      // TypeScript now knows session and user are non-null in subsequent handlers
      session: ctx.session,
      user: ctx.session.user,
    },
  });
});

// Admin middleware — must be used after isAuthed (pipes)
const isAdmin = t.middleware(async ({ ctx, next }) => {
  // ctx.user is typed as defined by isAuthed — no null check needed
  if (ctx.user.role !== 'admin') {
    throw new TRPCError({ code: 'FORBIDDEN', message: 'Admin access required' });
  }
  return next({ ctx });
});

// Timing middleware — logs procedure duration
const timingMiddleware = t.middleware(async ({ path, next }) => {
  const start = Date.now();
  const result = await next();
  console.log(`[tRPC] ${path} took ${Date.now() - start}ms`);
  return result;
});

export const publicProcedure = t.procedure.use(timingMiddleware);
export const protectedProcedure = publicProcedure.use(isAuthed);
export const adminProcedure = protectedProcedure.use(isAdmin);

Details

tRPC middleware is a functional chain: each middleware receives the current ctx and calls next() to pass control to the next middleware or the handler. The ctx passed to next() becomes the ctx available in subsequent middleware and the handler.

Context type narrowing: When middleware adds properties to ctx (e.g., user: NonNullable<Ctx['session']['user']>), TypeScript updates the ctx type for everything downstream. This is why protectedProcedure's handler can access ctx.user without null checks — the middleware has already asserted non-null.

Middleware composition: protectedProcedure.use(isAdmin) creates adminProcedure. Middleware applied earlier in the chain runs first. timingMiddleware.use(isAuthed).use(isAdmin) runs timing, then auth, then admin check, then the handler.

next() return value: Middleware can inspect the handler's return value by const result = await next() and then examine or transform result.ok / result.data. This pattern is useful for response logging and transforming output globally.

Procedure reuse pattern: Instead of applying middleware individually to each procedure, create named procedure builders (publicProcedure, protectedProcedure, adminProcedure) and use them as the base for all procedures in a domain. This guarantees consistent middleware application.

Input access in middleware: Middleware does not have access to the validated input by default. If middleware needs input values (e.g., for rate limiting by resource ID), use experimental_caller or restructure to check after input validation by placing middleware after .input().

Source

https://trpc.io/docs/server/middlewares

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.