Structuring with tRPC Routers

As your application grows, your API can become messy. tRPC routers help you organize your API into logical, reusable modules.

Think of a router as a folder for your API endpoints. Instead of one giant file, you group related operations together.

• Modularity: Break down complex APIs.
• Readability: Easier to understand specific parts.
• Scalability: Simplifies adding new features.

In tRPC, you create a router using trpc.router(). This function comes from your tRPC instance, which we assume is set up.

A router acts as a container for your API procedures (queries and mutations). Each router can have its own set of procedures.

Here's how you might define a simple "user" router:

const userRouter = t.router({
  // Procedures will go here
});

Once you have a router, you can add procedures to it. Procedures are the actual API endpoints that perform actions like fetching data (queries) or modifying data (mutations).

You attach procedures using methods like .query() or .mutation() directly to your router instance. For example, a user router might have a getById query.

const userRouter = t.router({
  getById: t.procedure
    .input(z.string())
    .query(({ input }) => {
      return { id: input, name: `User ${input}` };
    }),
});

Let's see a basic tRPC router for users. This example includes a minimal setup to make it runnable, focusing on the router definition.

The appRouter is our main router that will contain all others. Here, we're just setting up a single userRouter with a simple query.

Imagine an API for an e-commerce site. You might have operations for users, products, orders, and payments.

Putting all these into a single router would make it huge and hard to manage. Instead, you create a separate router for each logical domain:

• userRouter for user-related tasks.
• productRouter for product management.
• orderRouter for order processing.

This keeps your codebase tidy and promotes better teamwork.

Once you have multiple individual routers, you need a way to combine them into a single, unified API that your frontend can interact with. This is where router.merge() comes in.

You use .merge() on your main, "root" router to include all your sub-routers. This makes all procedures from the sub-routers available under a specific namespace, defined by the key you assign them to.

Let's expand our example to include a postRouter and then merge it with our userRouter into a single appRouter.

Notice how we attach each sub-router to a key (e.g., user: userRouter), creating a nested structure for our API calls.

Once routers are merged, your frontend client can access procedures using dot notation, reflecting the nested structure you defined.

• To call a user query: client.user.getById(...)
• To call a post query: client.post.getAll()
• To call a post mutation: client.post.create(...)

This clear naming convention makes your API intuitive and easy to navigate.

For larger projects, it's common to place each router in its own file. This keeps your codebase modular and easy to navigate.

A typical structure might look like this:

• src/server/trpc.ts (tRPC instance, root router definition)
• src/server/routers/user.ts (userRouter definition)
• src/server/routers/post.ts (postRouter definition)
• src/server/index.ts (server setup, merging routers)

You have a productRouter and an orderRouter. You want to combine them into your main appRouter so they can be accessed as client.product... and client.order....

Which code snippet correctly merges these routers?

You've learned how tRPC routers help organize your API into logical, manageable modules. By defining individual routers for different domains and then merging them into a root router, you create a scalable and maintainable API structure.

• t.router(): Creates a new router.
• Procedures: Added to routers using .query() or .mutation().
• Merging: Combine routers into a single API by assigning them to keys in the root router definition.

Next, you'll dive deeper into implementing specific query procedures!