tRPC v10 Router Architecture: Modularizing Server Instance and Router Definitions

Answer

1. Generic propagation in deeply nested routers

• In v10 the router is a t.router value created by the same initTRPC factory that produced the t object. All nested routers inherit the Context and Metadata generics that were fixed at initTRPC.context().create(). Because the router type is built from that factory, the compiler can compose the input/output types of every procedure structurally, no matter how many levels of nesting.
• As long as every feature router is built from the same t instance, the root AppRouter type will contain the exact procedure signatures of all nested routers. The separation of the router from the server adapter does not introduce a new generic boundary; the server adapter receives only a runtime value and never participates in the type derivation.

2. Tree‑shaking with shared middleware

• Shared middleware is attached to a router with router.use(middleware). The middleware becomes a transitive dependency of every procedure that calls .use(). In a bundler that performs tree‑shaking, any bundle that imports a router that uses the middleware will include the middleware code and all of its imports.
• Routers that do not import the shared middleware are unaffected – their code can be eliminated if the entry point never references them. This is why a serverless function that only needs a subset of routers can stay small: you simply omit the unused routers from the entry file.
• Because the router definition is a plain JavaScript value, the bundler sees it as a normal module import. Side‑effectful top‑level code inside a middleware module can prevent elimination, so keep middleware free of global side effects when you want maximum tree‑shaking.

Confirmed facts (tRPC v10)

• Routers and procedures must come from the same initTRPC factory; mixing factories with different Context generics causes a compile‑time error.
• The server adapter (Express, Fastify, Next, Lambda, etc.) only receives the router at runtime; its type signature never references Context or the procedure types.
• Client code can import the AppRouter type via import type { AppRouter } from "./router" and use createTRPCProxyClient() without pulling in any server runtime code.

Likely explanation / caveats

• Deeply nested routers can lead to very large type trees. In extreme cases you may hit TypeScript limits such as "type instantiation is excessively deep"; splitting the router into smaller namespaces or using project references can mitigate this.
• Middleware that augments the ctx (e.g., adding ctx.user) must be applied where the procedures that read it are defined. If you apply the middleware after a procedure that expects the augmentation, you’ll get a runtime error or a type mismatch.
• Tree‑shaking effectiveness depends on the bundler’s ability to detect unused imports. If a middleware module has top‑level side effects (e.g., logging, global state mutation), those effects may keep the module in the bundle even when no router uses it.

Practical steps to verify your setup

1. Confirm the installed major version: npm list @trpc/server should show 10.x before using the API names below.
2. Create a minimal router module that imports the shared t factory and builds a sub‑router:

   import { t } from "./trpc";
   export const postsRouter = t.router({
     create: t.procedure.input(z.object({ title: z.string() })).mutation(() => { /*...*/ })
   });
   

3. Compose the root router in a separate file, importing only the routers you need:

   import { t } from "./trpc";
   import { postsRouter } from "./posts";
   export const appRouter = t.router({ posts: postsRouter });
   export type AppRouter = typeof appRouter;
   

4. Run tsc --noEmit and inspect inferRouterOutputs<AppRouter> to ensure the nested procedure types are present.
5. Try merging a router built from a second initTRPC instance with a different Context type; TypeScript should surface an error, confirming the single‑factory rule.
6. Bundle the server entry with a tool like webpack-bundle-analyzer or rollup-plugin-visualizer and compare bundle sizes when you import versus omit a feature router.

Missing diagnostic detail

To refine the recommendation, could you confirm whether all feature routers are built from the same initTRPC factory and use a shared Context type? If you have per‑feature context augmentations, we may need to adjust the middleware strategy.