Course contentsShow
← TypeScript
Lesson 1547 of 1,79635. TypeScript with Framework Cross-ReferencesFree lesson

Nested Routers and Namespace Types

Organizing procedures into nested routers while maintaining end-to-end type safety across complex API structures.

Nested Routers and Namespace Types

What you'll learn: How to organize tRPC procedures into nested routers while maintaining complete end-to-end type safety across complex API structures.

The Scaling Challenge

As your tRPC API grows, putting all procedures in a single router becomes unmanageable. You need logical grouping—user operations separate from product operations, admin routes distinct from public ones. Nested routers let you organize procedures into hierarchical namespaces, and TypeScript preserves full type safety through every level.

Creating Nested Router Structures

You build nested routers by creating separate router instances and merging them into a parent using .merge() or by directly nesting them as properties:

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

const t = initTRPC.create();

// Separate domain routers
const userRouter = t.router({
  getById: t.procedure
    .input(z.object({ id: z.string() }))
    .query(({ input }) => ({ id: input.id, name: 'John' })),
  
  create: t.procedure
    .input(z.object({ name: z.string(), email: z.string() }))
    .mutation(({ input }) => ({ id: '123', ...input })),
});

const productRouter = t.router({
  list: t.procedure.query(() => [{ id: '1', name: 'Widget' }]),
  
  getById: t.procedure
    .input(z.object({ id: z.string() }))
    .query(({ input }) => ({ id: input.id, price: 29.99 })),
});

// Main app router with nested namespaces
export const appRouter = t.router({
  user: userRouter,
  product: productRouter,
});

export type AppRouter = typeof appRouter;

Type Safety Across Namespaces

On the client, TypeScript infers the complete nested structure. You call procedures using dot notation, and every level maintains full type inference:

// Client-side usage (assuming tRPC client setup)
// trpc.user.getById.query({ id: '123' }) // ✓ Types flow through
// trpc.product.list.query() // ✓ Knows this returns products

The namespace types preserve input schemas, output types, and procedure kinds (query vs mutation) at every nesting level. You get autocomplete for user and product, then for each procedure within them, then for the correct input shape.

Deeply Nested Organization

You can nest routers multiple levels deep for complex applications:

const publicRouter = t.router({
  user: userRouter,
  product: productRouter,
});

const adminUserRouter = t.router({
  delete: t.procedure
    .input(z.object({ id: z.string() }))
    .mutation(({ input }) => ({ success: true })),
});

const adminRouter = t.router({
  user: adminUserRouter,
});

export const appRouter = t.router({
  public: publicRouter,
  admin: adminRouter,
});

// Usage: trpc.admin.user.delete.mutate({ id: '123' })

Each layer remains fully typed—TypeScript knows admin.user.delete is a mutation requiring an id string.

Key Takeaway: Nested routers let you organize tRPC APIs into logical namespaces without sacrificing type safety—TypeScript maintains complete type inference through every level of the router hierarchy, giving you autocomplete and validation from the top-level namespace down to individual procedure inputs and outputs.