DEV Community: James Conlon

Building Blocks of TRPC - Part 1

James Conlon — Fri, 14 Mar 2025 17:34:39 +0000

This is a primer on using TRPC on your Typescript backend. It assumes familiarity with Typescript and some basic server concepts. It's written for NextJS but it's suitably broad to apply to any Typescript framework (Deno, Bun, etc.).

It's also deliberately quite high-level. It's missing a lot of the good stuff they put in the frontend. To see more of what you're missing out on, reference the official docs here.

Once you've got the pattern down you can move to part 2, where we'll learn how to customise TRPC for our needs.

Standard Configuration

Throughout this guide I will refer to "standard configuration". This is the typical setup encountered when we see TRPC integrated into NextJS. I am using the default configuration provided by T3 Stack. It has become the de facto standard for TRPC integration and can be taken as a best practices example. You can familiarise yourself by spinning up a new T3 Stack project and selecting TRPC.

Visualising TRPC

Disclaimer: This diagram is not 100% accurate. Nor is it 90% accurate. But it does make sense! Reference this as you work through each section.

Context

Context is a simple but important concept in TRPC. It affects everything you see in the hierarchy.

Context definition (from the docs):

Stuff that every procedure can access

That nicely sums it up tbh.

// src/trpc/server.ts
export const createTRPCContext = async (opts: { headers: Headers }) => {
    const session = await getServerAuthSession();

    return {
        db,
        session,
        ...opts,
    };
};

createTRPCContext is a function that returns the context object.

db: Database object from a database provider or ORM of your choice
session: Session object from AuthJS
opts: Headers from the incoming request

The TRPC object "t"

The TRPC object is a collection of related things. It's called "t" because naming things is hard.

// src/server/api/trpc.ts
const t = initTRPC.context<typeof createTRPCContext>().create({
    transformer: superjson,
    errorFormatter({ shape, error }) {
        return {
            ...shape,
            data: {
                ...shape.data,
                zodError:
                    error.cause instanceof ZodError ? error.cause.flatten() : null,
            },
        };
    },
});

We create t by calling initTRPC with type of our context. This is what guarantees type safety the whole way down the chain. It also locks us in to that context. We will need to create an entirely new TRPC instance if we want to do anything different.

transformer: a transformer is applied to the data when transmitted between server and client. Here we use superjson to maintain type safety between the two.
errorFormatter: formats any errors for us. Assuming it's a zod error, it will give us better formed error descriptions.

Caller

Does what it says on the tin. A caller is a piece of Javascript that calls a procedure. In standard configuration this is created as a helper and is injected into the client Javascript at hydration.

// src/server/api/trpc.ts
export const createCallerFactory = t.createCallerFactory;

t comes with a factory function

// src/server/api/root.ts
export const createCaller = createCallerFactory(appRouter);

We make createCaller with the factory function. It's based based on a router. We can use this mechanism to limit the procedures our callers have access to.

// src/trpc/server.ts
const createContext = cache(() => {
  const heads = new Headers(headers());
  heads.set("x-trpc-source", "rsc");

  return createTRPCContext({
    headers: heads,
  });
});

const caller = createCaller(createContext);

export const { trpc: api, HydrateClient } = createHydrationHelpers<AppRouter>(
  caller,
  getQueryClient
);

createContext is wrapped around the createTRPCContext that we defined above. Don't let that confuse you. They are functionally identical. This is just used to set an extra header on the request. Not strictly necessary but good practice.

Finally the caller is created with the parent context from the beginning. This is packaged into a helper and shipped directly into the client with the page's javascript.

We are not limited to this though. We can create callers and use them to call procedures wherever we like: e.g. on a server event or an api route. More on this in part 2.

Router

A router is a logical collection of procedures. Routers can be grouped together in a hierarchy. In standard configuration you create separate routes for posts, comments, etc. and they are all grouped together under a single AppRouter.

// src/server/api/root.ts
export const appRouter = createTRPCRouter({
  post: postRouter,
  comment: commentRouter,
});

But routers are more useful than just logical groupings. For example, in your client code, you can easily do something like this.

await utils.comment.invalidate();

This will invalidate the cache for every procedure in a router and force a refetch of the data. This is often more desirable than refetching a single pice of data or the entire page. TRPC client is heavily integrated with TanStack Query and it's full of nifty features like this.

Procedure

A procedure is one unit of work in TRPC. Equivalent to a single API call.

We can create infinite types of procedures. What makes these procedure types different usually depends on the type of middleware they use. In standard config there are two procedure types:

Public: Uses no middleware and can be accessed by anyone.
Protected: Validates all user sessions sent with the request. It can only be accessed by authenticated users.

// src/server/api/trpc.ts
export const publicProcedure = t.procedure.use(timingMiddleware);

publicProcedure is just a barebones procedure. Here timingMiddleware is used to time the duration of each request but this is really just for fun. Otherwise, this procedure is completely exposed to the outside world.

// src/server/api/trpc.ts
export const protectedProcedure = t.procedure
  .use(timingMiddleware)
  .use(({ ctx, next }) => {
    if (!ctx.session || !ctx.session.user) {
      throw new TRPCError({ code: "UNAUTHORIZED" });
    }
    return next({
      ctx: {
        // infers the `session` as non-nullable
        session: { ...ctx.session, user: ctx.session.user },
      },
    });
  });

protectedProcedure contains some middleware (an inline function). The middleware looks for the session associated with the request context. If it does not exist the request is rejected before ever reaching the content of the procedure. In this way we can guarantee that all protectedProcedures have been previously authenticated.

We are not limited to just these two types of procedure. For example, it would be an easy step to check the user's role and expand these definitions to cover userProcedure, moderatorProcedure and adminProcedure. This way we can guarantee that all procedure calls downstream are appropriately authorised every time. If not, they will simply fail.

Summary

Hopefully this breakdown has been valuable. If that all sounded like nonsense, go and spin up a TRPC project, write a little API and then come back here. Most of these terms will become familiar with a little exposure. Also, reference the diagram as you read your code. It illustrates the relationship between all these components pretty neatly.

If that was a walk in the park for you then head over to part 2 where we will be breaking these components apart and (if there's time) putting them back together!

Tic-Tac-Toe Hard Mode

James Conlon — Sat, 04 May 2024 11:44:32 +0000

Anyone who knows React is probably familiar with the famous tic-tac-toe example from the training docs. It covers most of the basic priciples of React in one single project. It also includes a handful of challenges at the end to help you expand on what you've learned. I distinctly remember not being able to do any of them and quitting immediately. Well who's laughing now? (Me)

Anyway, we do it because it's there. Keep reading and I guarantee you'll find something you disagree with.

1. Change button to text

For the current move only, show “You are at move #…” instead of a button.

Full Solution on Codesandbox

Nice easy one to start. The final button in the list does nothing so we replace it with a plain text message.

This is simple enough to do with a ternary inside the component. We already map each move to a list item <li>. Now inside each list item we check to see if it's the final element (remember -1 because zero index). Then we return either a string or a button.

<li key={move}>
  {move === history.length - 1 ? (
    `You are at move #${move}`
  ) : (
    <button onClick={() => jumpTo(move)}>{description}</button>
  )}
</li>

2. Refactor Board

Rewrite Board to use two loops to make the squares instead of hardcoding them.

Full Solution on Codesandbox

This is purely a refactor. Only the code will change. The actual rendered app and functionality will remain exactly the same.

First we'll try the nice solution. The one that I want to work. I want it to work so bad!

const boardLayout = [...Array(9).keys()].map((i) => (
  <Square value={squares[i]} onSquareClick={() => handleClick(i)} />
));

Look how neat that is! They key bit here is [...Array(9).keys()]. This is a time-honoured javascript hack that acts as our equivalent of a range function in any other language Basically, create an array of 9 elements, get the keys of those elements (0, 1, 2, ...) and then spread those keys out into an array. This lets me nicely map out the same element nine times using a single line of code. But... there's a catch!

Yep, that's not right! We have forgotten to add the row container. This means that instead of using my catchy one-liner from above we are going to have to perform an unholy combination of logic and layout. So we end up with the code below. It's a loop within a loop, as specified. Three rows, three columns. It's definitely not as pretty, but pretty wasn't the challenge.

const boardLayout = [...Array(3).keys()].map((row) => (
  <div className="board-row">
    {[...Array(3).keys()].map((col) => {
      const i = row * 3 + col;
      return <Square value={squares[i]} onSquareClick={() => handleClick(i)} />;
    })}
  </div>
));

Replacing the original static layout with a new dynamic one has pros and cons. Pro: we reduce repeated code and make it more maintainable. Con: We replace a simple layout with much more convoluted logic, making the code much less readable. In this case I would always prefer the static layout but dynamic layouts are very common and are much more maintainable in larger apps.

3. Toggle

Add a toggle button that lets you sort the moves in either ascending or descending order.

Full Solution on Codesandbox

This one is super easy!

The layout for our moves currently looks like this: <ol>{moves}</ol>.
Here moves is nothing but an array of JSX elements. Why not swap them around like so <ol>{moves.reverse()}</ol>?

This is perfectly fine to do because moves isn't state. It is derived from state, i.e. moves = history.map(). Crucially, the map function creates a copy of the array that we can mutate as much as we like. No state problems here officer!

Obviously, that's not exactly everything. I'll add a single piece of boolean state, toggle it with a button and check it before reversing.

return (
  <div className="game">
    <div className="game-board">
      <Board xIsNext={xIsNext} squares={currentSquares} onPlay={handlePlay} />
    </div>
    <div className="game-info">
      <ol reversed={isMovesReversed}>
        {isMovesReversed ? moves.reverse() : moves}
        <br />
        <button onClick={() => setIsMovesReversed(!isMovesReversed)}>
          {isMovesReversed
            ? "Show moves in ascending order"
            : "Show moves in descending order"}
        </button>
      </ol>
    </div>
  </div>
);

And bingo! Note that isMovesReversed is used to control the order of the moves elements and the text on the button. Using ternarys for simple logic like this is perfectly fine.

One side note that I hadn't thought about is that this is an ordered list. It doesn't care what order the array is in. It just counts elements starting from 1. Luckily HTML came pre-bundled with a solution for that. <ol> in native HTML has a reversed attribute. We can just tie that to isMovesReversed. Beautiful native HTML!

4. Winning streak

Full Solution on Codesandbox

When someone wins, highlight the three squares that caused the win (and when no one wins, display a message about the result being a draw).

The good news with this one is that all the heavy lifting of calculating the winner has already been done. The original solution contains the following.

const lines = [
  [0, 1, 2],
  [3, 4, 5],
  [6, 7, 8],
  [0, 3, 6],
  [1, 4, 7],
  [2, 5, 8],
  [0, 4, 8],
  [2, 4, 6],
];

lines defines every possible combination that could be considered a straight line on the board. calculateWinner checks if all three have the same value and then returns that value. If we adapt calculateWinner we can have it also return the specific combination that won. Sounds super useful!

return [squares[a], lines[i]];

This is what that looks like. The function now returns two values. So it's important we remember to destructure those two values everywhere we use it.

const [winner, winnerLine] = calculateWinner(squares);

Like so. The first bit winner is used for it's original purpose. The second bit winnerLine will go on to do great things.

But first we have to consider the actual square component. How do we make it turn green? In react we can pass inline CSS as a simple object to the style prop.

function Square({ value, onSquareClick }) {
  return (
    <button
      style={{ background: "green" }}
      className="square"
      onClick={onSquareClick}
    >
      {value}
    </button>
  );
}

You will see every square has now turned green. That's what we wanted right? Damn! Ok, let's make it conditional on some prop isWinner. We'll figure out what that is later.

function Square({ value, onSquareClick, isWinner }) {
  return (
    <button
      style={isWinner ? { background: "green" } : {}}
      className="square"
      onClick={onSquareClick}
    >
      {value}
    </button>
  );
}

Uh-oh! It's later already. How are we going to tell this square if it's a winner or not? Remember when I said winnerLine would go on to do great things? Turns out we can just check the square number, and if it's in winnerLine, it's a winner!

<Square
  value={squares[i]}
  onSquareClick={() => handleClick(i)}
  isWinner={winnerLine && winnerLine.includes(i)}
/>

It's that easy! Note, we check if it exists first. winnerLine only exists once a winner has been determined.

One more thing. We need a stalemate message. Stalemate occurs when we reach the final move and there is no winner. I think the easiest way to achieve this is to give the board an extra prop currentMove and pass this down from App. Nothing super clever here just a few mutually exclusive if statements to cover all our cases.

if (winner) {
  status = "Winner: " + winner;
}
if (!winner && currentMove === 9) {
  status = "Stalemate!";
}
if (!winner && currentMove !== 9) {
  status = "Next player: " + (xIsNext ? "X" : "O");
}

It's not perfect but it will cover every case we will encounter here.

5. Move Locations

Display the location for each move in the format (row, col) in the move history list.

Full Solution on Codesandbox

Like the prompt said. Display the board coordinates of each move.

Currently state is used to track two things

history
currentMove

We could add an extra piece of state. i.e. for each move we store a number that represents the location of that move. That's cool, but we would have to ensure we keep that new state in sync with the history at all times. Not so easy, especially in a larger app. We could also augment history into an object so it could store more detailed information. That sounds like a better option but can we go even better? Can we use what we already have?

By comparing the board between any two given moves we can determine the location of the move. All this information already exists in state, we just calculate what we want on the render. It's definitely putting some computation onto each render but I think here we will get away with it.

function getMoveIndex(oldSquare, newSquare) {
  if (oldSquare && newSquare) {
    for (let i = 0; i < oldSquare.length; i++) {
      if (oldSquare[i] !== newSquare[i]) {
        return i;
      }
    }
  }

  return -1;
}

Basically, give me two squares: old and new. Run through the each element of the squares until you find two values that aren't the same. That's the index that changed! The default case (-1) is to cover the first move where a previous move does not exist.

function indexToCoords(i) {
  if (i >= 0 && i <= 8) {
    return `[${Math.floor(i / 3) + 1}, ${(i % 3) + 1}]`;
  }
  return "";
}

It's trivial to go from an index value to a row/column value but it looks terrible. All that logic is neatly wrapped in indexToCoords.

const coords = indexToCoords(getMoveIndex(history[move - 1], history[move]));

Finally, for each move in history we just calculate coords (as in coordinates). Now you can use coords wherever you want to display the string. Note that on the first pass history[move - 1] actually becomes history[-1] which is undefined. This is why we setup getMoveIndex to handle undefined input.

Epilogue

I think these were useful challenges. Refactoring and retooling code forces you to make a million small design decisions every day. These exercises do a nice job of exposing them at a small scale. Hopefully all the little decisions I've made here are defensible. If not, fight me in the comments. What would you do differently?