11 October 2022
by
Hector Sosa's profile photo, Webscope.io
Hector Sosa

tRPC: Understanding Typesafety

typescript
trpc
next.js
Type safety is the extent to which a programming language prevents type errors. The process of verifying and enforcing the constraints of types may occur at compile time or run-time. A programming language like TypeScript checks a program for errors before execution (at compile time) as a static type checker.
In contrast, a library like Zod can also provide type checking at run-time. So how does a library like tRPC helps us better understand type safety?
„tRPC allows you to easily build and consume fully typesafe APIs, without schemas or code generation.“
At its core, tRPC provides the solution to statically type our API endpoints and share those types between our client and server, enabling type safety from end-to-end.

How does tRPC share types between client/server?

Types are shared based on one or many procedures contained in Routers. A procedure is a composable query, mutation, or subscription where you define how your client/server interacts with each other.
Let's see what you'd need to create a query procedure for a Next.js application. We'll explore these concepts by reviewing our tRPC-basic-starter GH repo. Here's what our file structure initially looks like:
# @path: ./src├── pages│   └── api/trpc│       └── [trpc].ts # <-- tRPC HTTP handler│   └── _app.tsx      # <-- tRPC Provider│   └── index.tsx│   └── [...]├── server│   └── routers│       └── _app.ts   # <-- Main app router│       └── user.ts   # <-- User sub-router│       └── [...]     # <-- More sub-routers│   └── trpc.ts       # <-- Procedure helpers├── utils│   └── trpc.ts       # <-- Typesafe tRPC hooks
You could define all of your procedures within the tRPC HTTP handler and completely skip the server directory. However, this wouldn't be a scalable approach. Your backend will likely require several endpoints, for which it is recommended to separate your procedures into different sub-routers and merge them as suggested in the file structure above.
To create a query procedure, at the most basic level we need to define an input (optional and validated with your library of choice), and a query (the actual implementation of the procedure) which runs a function returning the data you need. In the end, the types of each router are exported to provide a fully-typed experience on the client without importing any server code.
// @path: ./src/server/routers/user.tsimport { t } from "../trpc";import { z } from "zod";export const userRouter = t.router({    // Define a procedure (function) that    // ...takes an input and provides a query    // ...as `user.greet.useQuery()`    greet: t.procedure        // Input validation        .input(z.object({ name: z.string() }))        .query(({ input }) => {            // Here you would process            // any information you'd need            // ..to return it to your client            return { text: `Hello, ${input.name}!` };        }),});

Using your new tRPC-backend on the client

@tRPC/react provides a set of hooks wrapped around @tanstack/react-query, so under the hood, they work just the same to fetch data from a server. You'll notice that the conventional querying keys and functions are defined within your procedure.
// @path: ./src/pages/index.tsximport { trpc as t } from "../utils/trpc";export default function Home() {    // Wrapped around @tanstack/react-query    // Can also destructure to access    // isLoading, isError, isSuccess, error and data    const result = t.user.greet.useQuery({ name: "Client" });    if (result.isLoading) {        return (            <div>                <h1>Loading...</h1>            </div>        );    }    return (        <div>            <h1>{result.data?.text}</h1>        </div>    );}
...and that's the basic setup. Both the result and input are type-inferred from the procedures as defined and will get TypeScript autocompletion and IntelliSense that matches your backend API without requiring any code generation.

More examples of tRPC usage

Let's create an additional sub-router @path: ./src/server/routers/post.ts where we need to provide our client with the following: (a) fetch all posts, (b) fetch post by ID, (c) create a new post. Notice that requirements for a and b are different than for c, as the first two are query procedures and the last one requires a mutation procedure. However, you will notice that there is no difference between queries and mutation apart from semantics.
import { t } from "../trpc";import { z } from "zod";type PostType = {    userId: number;    id: number;    title: string;    body: string;};export const postRouter = t.router({    // Define a procedure that    // ...doesn't require an input and provides a query    // ...as `post.allPosts.useQuery()`    allPosts: t.procedure.query(async () => {        const allPosts = await fetch(            "https://jsonplaceholder.typicode.com/posts"        ).then((response) => response.json());        return { posts: posts as Array<PostType> };    }),    // Define a procedure that    // ...takes an id and provides a query    // ...as `post.postById.useQuery({ id })`    postById: t.procedure        .input(z.object({ id: z.string() }))        .query(async ({ input }) => {            const post = await fetch(                `https://jsonplaceholder.typicode.com/posts/${input.id}`            ).then((response) => response.json());            return { post: post as PostType };        }),});

How can we use procedures?

Procedures are able to resolve any custom function to process a validated { input }. Just to name a few examples: you could make use of an ORM like Prisma, a Baas like Supabase, or a headless CMS like Sanity to process your data with the benefits of fully typesafe APIs.

What about Mutations?

Mutations are typically used to create/update/delete data. Let's take a look at how we could create a mutation procedure using our Post sub-router:
import { t } from "../trpc";import { z } from "zod";type PostType = {    userId: number;    id: number;    title: string;    body: string;};export const postRouter = t.router({    // Define a procedure that    // ...takes an id and executes a mutation    // ...as `post.createPost.useMutation()`    // ...from `*.mutate({ input })`    createPost: t.procedure        .input(            z.object({                title: z.string().min(1),                body: z.string().min(1),                userId: z.number(),            })        )        .mutation(async ({ input }) => {            const post = await fetch(                "https://jsonplaceholder.typicode.com/posts",                { method: "POST", body: JSON.stringify(input) }            ).then((response) => response.json());            return { response: post as PostType };        }),});
Here is how we could execute the mutation from the client:
import { FormEvent, ChangeEvent, useState } from "react";import { trpc as t } from "../../utils/trpc";export default function NewPost() {    // User is fixed for simplicity    const initValue = { title: "", body: "", userId: 1 };    const [form, setForm] = useState(initValue);    const mutation = t.post.createPost.useMutation();    function handleChange(        e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement>    ) {        setForm({ ...form, [e.target.id]: e.target.value });    }    function handleSubmit(e: FormEvent<HTMLFormElement>) {        e.preventDefault();        mutation.mutate(form);        setForm(initValue);    }    return (        <form onSubmit={handleSubmit}>            <label htmlFor="title">Title</label>            <input                type="text"                id="title"                name="title"                value={form.title}                onChange={handleChange}            />            <label htmlFor="body">Body</label>            <textarea                id="body"                name="body"                value={form.body}                onChange={handleChange}            />            <button type="submit">Submit</button>        </form>    );}
Mutations are as simple to do as queries, they're actually the same underneath, but are just exposed differently as syntactic sugar and produce an HTTP POST rather than a GET request.

So WIFY by using tRPC?

What's in it for you using tRPC? We barely scratched the surface, here is a list of features:
  • Full static type-safety with auto-completion on the client, inputs, outputs, and errors.
  • No code generation, run-time bloat, or build pipeline.
  • Zero dependencies and a tiny client-side footprint.
  • All requests can be batched automatically into one.
  • Framework agnostic and compatible with all JavaScript frameworks and runtimes.
Feel free to explore this example using the resources below:
Share post

Let’s stay connected

Do you want the latest and greatest from our blog straight to your inbox? Chuck us your email address and get informed.
You can unsubscribe any time. For more details, review our privacy policy

Related posts