[Proposal] tRPC as communication between front and back

[JoaquinTrinanes]

(I'm opening this as an issue because we don't have discussions enabled)

The rant

There are a LOT of things that can go wrong when communicating between front and back through an API. One of the most commons issue I've encountered was the typing system and schema validation. We can send whatever we want to whatever endpoint, and it's a responsibility of both the front and back team to coordinate and determine this.
There are many popular solutions for this:

• OpenAPI specification. That is, a file that lives outside of the code and sometimes the project. It instructs the available endpoints and how to communicate with them. Sometimes it's generated automatically using tools that analyse the existing APIs, but if the feature to develop is new it would block the front team until it's completed, so it should be written beforehand. This method is beloved by JS and Python developers because it allows the developer to break the contract without consequences (during linting or build time) (we use this! 🎉 )
• GraphQL. What if we host the specification on a server, version it and create a typed wrapper around it? GraphQL is the standard de-facto for type-safe API consumption, but it implies a huge developer overhead (also the schema has to be synched every time you change it)

During the past weeks, I had to do a HUGE change in one of my Next.js personal projects. What was originally a static site that read data from a CMS turned into an application that also provided CRUD access to a database, authorization, magic link sign-in, user roles...

I felt a little hopeless at first, as I don't really enjoy creating a file per Next endpoint, and then, per each file, add the following:

1. Guards to avoid calling a not allowed method

switch (req.method) {
  case 'GET':
      ...
  default:
      return res.status(405);

2. Type validation, to ensure the body I received (of type unknown) was correct. That validation can be different depending on the HTTP method.
3. When consuming the API, cast the response type to what I expected the endpoint to return.

return response.data as ResponseInterventionsData; // this won't fail if the response type is different

Current situation

We don't use Next.js endpoint's at Vizz that I know of (except for specific cases like authentication), but the problems described above exist consuming an external API too. The backend team has to create a DTO to validate the data, the frontend team has to cast whatever arrives to something usable. And there's a Swagger somewhere (that being said, in comparison to my other jobs, you do a great work being faithful to the specification, even though I found some documentation without response type in the wild that I had to check by hand).

When the specification changes, the backend has to change both the spec and the DTOs. The front has to modify the interfaces they created to do their castings (usually from the spec) This is not ideal because [object Object].

There's got to be a better way, right? RIGHT?

Enter tRPC

The thing I like about tRPC is the first thing that appears when you open the page

In a nutshell, tRPC provides inferred, type safe Remote Procedure Calls.

This is the workflow when creating a tRPC method (I'll use v9 syntax, v10 is on the way but still in beta):

1. Add the call to the router:

const appRouter = trpc.router().query('hello', {
  resolve: async () =>  {
    return 'Hello world!'
  },
});

2. We can add input and output validation! With the power of zod, we can create a validation schema and infer the type of that schema, instead of the other way around. This schema is the only type definition we'll need. At all.

import { z } from 'zod';
  const appRouter = trpc.router().query('hello', {
    input: z.string().min(1).default('world'),
    resolve: async ({ input }) =>  { // input is of type string :D
      return `Hello ${input}!`
    },
  })
  .mutation('updateUser', {
    // ...
  });

This validation works with complex nested objects too (objects, arrays, sets, enums...)

3. If using Next.js' API, there's a single endpoint that needs to be configured. There's a custom official adapter for that.
4. To call the methods from the client, we just import them (this is a React example, but there's a way to use this without hooks outside of react of course).

import { createReactQueryHooks } from '@trpc/react';
import type { AppRouter } from '../pages/api/trpc/[trpc]';

export const trpc = createReactQueryHooks<AppRouter>();

Note how we never import server code in the client, we just import the AppRouter type. The created hooks are totally type safe now!

const { data: message, isSuccess } = trpc.useQuery(['hello']);

There are a few things to note about the code above:

• react-query is used internally
• The hello string has type hinting. In v10 of tRPC, objects instead of strings are used. This allows to click go to definition and somehow being redirected to the backend code (with black magic or something)
• There's autocomplete for a second array element, a string, the optional parameter of the call.
• We just defined one schema, and have full type safety in both the server and client. If the server code changes, the compiler will detect it beforehand.

The proposal itself

Thanks for reading so far! Given our current project structure (monorepo) I think this can improve the quality and stability of our code, save time and make us work more efficiently. I have two proposals:

1. Make use of Next.js' API routes and use tRPC. I'm not sure about what the backend team might lack with this approach, but it would keep all our code in a single repo and it would allow collaboration outside of our functional area without having to wait for a fix.
2. Use the tRPC client on our client repo, and propose the back team to host a tRPC server. I'm sure there's a magic Typescript way to import the AppRouter type, the only type we need in the client (adding an include path in the tsconfig?) (edit: is this legal? it's much easier than I thought 😅)

I think the advantages of this approach are huge and measurable, let me know what you think! :)

FAQ

• What if we need to provide an API to a third-party as part of the project?
  • trpc-openapi creates the OpenAPI specification AND the REST endpoints themselves.
• Nobody asked anything yet!
  • Yes, errors are typesafe too
• I want to try it!
  • There's a playground here. It's for the v10 though, so keep in mind the syntax might (confirmed will) change in the near future a bit.