tRPC Full-Stack Type Safety

# tRPC Full-Stack Type Safety for Google Antigravity

tRPC enables fully type-safe APIs without code generation. Google Antigravity's Gemini 3 helps you build robust tRPC routers with intelligent procedure suggestions and error handling patterns.

## tRPC Server Setup

Configure the tRPC server with context and middleware:

```typescript
// server/trpc.ts
import { initTRPC, TRPCError } from "@trpc/server";
import { ZodError } from "zod";
import superjson from "superjson";
import { auth } from "@/lib/auth";
import { db } from "@/db";

interface CreateContextOptions {
  headers: Headers;
}

export const createTRPCContext = async (opts: CreateContextOptions) => {
  const session = await auth();

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

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,
      },
    };
  },
});

export const createCallerFactory = t.createCallerFactory;
export const createTRPCRouter = t.router;

export const publicProcedure = t.procedure;

export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
  if (!ctx.session?.user) {
    throw new TRPCError({ code: "UNAUTHORIZED" });
  }
  return next({
    ctx: {
      session: { ...ctx.session, user: ctx.session.user },
    },
  });
});

export const adminProcedure = protectedProcedure.use(({ ctx, next }) => {
  if (ctx.session.user.role !== "admin") {
    throw new TRPCError({ code: "FORBIDDEN" });
  }
  return next({ ctx });
});
```

## Router Definition

Create modular routers for your API:

```typescript
// server/routers/user.ts
import { z } from "zod";
import { TRPCError } from "@trpc/server";
import { createTRPCRouter, publicProcedure, protectedProcedure, adminProcedure } from "../trpc";
import { users, posts } from "@/db/schema";
import { eq, ilike, or, desc, sql } from "drizzle-orm";

export const userRouter = createTRPCRouter({
  me: protectedProcedure.query(async ({ ctx }) => {
    const user = await ctx.db.query.users.findFirst({
      where: eq(users.id, ctx.session.user.id),
      with: {
        posts: {
          limit: 5,
          orderBy: [desc(posts.createdAt)],
        },
      },
    });

    if (!user) {
      throw new TRPCError({ code: "NOT_FOUND" });
    }

    return user;
  }),

  getById: publicProcedure
    .input(z.object({ id: z.string().uuid() }))
    .query(async ({ ctx, input }) => {
      const user = await ctx.db.query.users.findFirst({
        where: eq(users.id, input.id),
        columns: {
          id: true,
          name: true,
          avatarUrl: true,
          createdAt: true,
        },
      });

      if (!user) {
        throw new TRPCError({ code: "NOT_FOUND" });
      }

      return user;
    }),

  list: adminProcedure
    .input(
      z.object({
        page: z.number().min(1).default(1),
        limit: z.number().min(1).max(100).default(10),
        search: z.string().optional(),
      })
    )
    .query(async ({ ctx, input }) => {
      const { page, limit, search } = input;
      const offset = (page - 1) * limit;

      const whereClause = search
        ? or(
            ilike(users.name, `%${search}%`),
            ilike(users.email, `%${search}%`)
          )
        : undefined;

      const [data, total] = await Promise.all([
        ctx.db.query.users.findMany({
          where: whereClause,
          limit,
          offset,
          orderBy: [desc(users.createdAt)],
        }),
        ctx.db.select({ count: sql`count(*)` }).from(users).where(whereClause),
      ]);

      return {
        data,
        pagination: {
          page,
          limit,
          total: Number(total[0]?.count ?? 0),
          totalPages: Math.ceil(Number(total[0]?.count ?? 0) / limit),
        },
      };
    }),

  update: protectedProcedure
    .input(
      z.object({
        name: z.string().min(2).max(100).optional(),
        avatarUrl: z.string().url().optional(),
      })
    )
    .mutation(async ({ ctx, input }) => {
      const [user] = await ctx.db
        .update(users)
        .set({ ...input, updatedAt: new Date() })
        .where(eq(users.id, ctx.session.user.id))
        .returning();

      return user;
    }),
});
```

## Root Router

Combine all routers:

```typescript
// server/routers/_app.ts
import { createTRPCRouter } from "../trpc";
import { userRouter } from "./user";
import { postRouter } from "./post";

export const appRouter = createTRPCRouter({
  user: userRouter,
  post: postRouter,
});

export type AppRouter = typeof appRouter;
```

## Next.js API Handler

Set up the API endpoint:

```typescript
// app/api/trpc/[trpc]/route.ts
import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
import { appRouter } from "@/server/routers/_app";
import { createTRPCContext } from "@/server/trpc";

const handler = (req: Request) =>
  fetchRequestHandler({
    endpoint: "/api/trpc",
    req,
    router: appRouter,
    createContext: () =>
      createTRPCContext({
        headers: req.headers,
      }),
    onError:
      process.env.NODE_ENV === "development"
        ? ({ path, error }) => {
            console.error(`tRPC error on ${path}:`, error);
          }
        : undefined,
  });

export { handler as GET, handler as POST };
```

## Client Setup

Configure the tRPC client:

```typescript
// lib/trpc/client.ts
"use client";

import { createTRPCReact } from "@trpc/react-query";
import type { AppRouter } from "@/server/routers/_app";

export const trpc = createTRPCReact<AppRouter>();
```

```typescript
// lib/trpc/provider.tsx
"use client";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { httpBatchLink } from "@trpc/client";
import { useState } from "react";
import superjson from "superjson";
import { trpc } from "./client";

export function TRPCProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient());
  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [
        httpBatchLink({
          url: "/api/trpc",
          transformer: superjson,
        }),
      ],
    })
  );

  return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </trpc.Provider>
  );
}
```

## Using tRPC in Components

Consume the API with full type safety:

```typescript
// components/UserProfile.tsx
"use client";

import { trpc } from "@/lib/trpc/client";

export function UserProfile() {
  const { data: user, isLoading, error } = trpc.user.me.useQuery();
  const updateMutation = trpc.user.update.useMutation({
    onSuccess: () => {
      utils.user.me.invalidate();
    },
  });
  const utils = trpc.useUtils();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!user) return null;

  const handleUpdate = (name: string) => {
    updateMutation.mutate({ name });
  };

  return (
    <div>
      <h1>{user.name}</h1>
      <button onClick={() => handleUpdate("New Name")}>
        {updateMutation.isPending ? "Updating..." : "Update Name"}
      </button>
    </div>
  );
}
```

## Best Practices

1. **Use Zod for input validation** - Ensures type-safe inputs
2. **Create middleware for auth** - Reusable authentication logic
3. **Batch requests** - Use httpBatchLink for efficiency
4. **Handle errors gracefully** - Use TRPCError with proper codes
5. **Invalidate queries on mutations** - Keep UI in sync

tRPC with Google Antigravity enables seamless full-stack TypeScript development with automatic type inference.