Build a Type-Safe Full-Stack API with tRPC

// src/schemas/project.ts — Shared validation schemas for the project domain.
// These are imported by both tRPC procedures and frontend forms,
// so a single change here propagates everywhere.

import { z } from "zod";

export const CreateProjectInput = z.object({
  name: z
    .string()
    .min(3, "Project name must be at least 3 characters")
    .max(100, "Project name must not exceed 100 characters"),
  description: z.string().max(2000).optional(),
  color: z
    .string()
    .regex(/^#[0-9a-fA-F]{6}$/, "Color must be a valid hex code")
    .default("#6366f1"),
  visibility: z.enum(["private", "team", "public"]).default("team"),
});

export type CreateProjectInput = z.infer<typeof CreateProjectInput>;

export const UpdateProjectInput = CreateProjectInput.partial().extend({
  id: z.string().cuid(),
});

export const ProjectFilters = z.object({
  visibility: z.enum(["private", "team", "public"]).optional(),
  search: z.string().max(200).optional(),
  cursor: z.string().cuid().optional(),
  limit: z.number().int().min(1).max(100).default(20),
});

// src/server/trpc.ts — tRPC initialization with typed context and middleware.
// The context factory runs on every request and makes the database client
// and authenticated user available to all procedures.

import { initTRPC, TRPCError } from "@trpc/server";
import { type CreateNextContextOptions } from "@trpc/server/adapters/next";
import superjson from "superjson";  // Handles Date, Map, Set serialization
import { prisma } from "@/lib/prisma";
import { getServerSession } from "@/lib/auth";

export const createTRPCContext = async (opts: CreateNextContextOptions) => {
  const session = await getServerSession(opts.req);
  return {
    prisma,               // Database client — available in every procedure
    session,              // null for unauthenticated requests
    requestId: crypto.randomUUID(),  // Trace ID for logging
  };
};

const t = initTRPC.context<typeof createTRPCContext>().create({
  transformer: superjson,
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        // Expose Zod validation errors in a frontend-friendly format
        zodError:
          error.cause instanceof z.ZodError
            ? error.cause.flatten()
            : null,
      },
    };
  },
});

export const router = t.router;
export const publicProcedure = t.procedure;

// Auth middleware — rejects unauthenticated requests before the procedure runs
const enforceAuth = t.middleware(({ ctx, next }) => {
  if (!ctx.session?.user) {
    throw new TRPCError({
      code: "UNAUTHORIZED",
      message: "You must be signed in to perform this action",
    });
  }
  return next({
    ctx: {
      ...ctx,
      user: ctx.session.user,  // Narrows type from `User | null` to `User`
    },
  });
});

export const protectedProcedure = t.procedure.use(enforceAuth);

// src/server/routers/project.ts — Project domain router.
// Procedures are thin orchestrators: validate input, call Prisma, return data.
// Business logic beyond simple CRUD belongs in src/services/.

import { router, protectedProcedure } from "../trpc";
import { CreateProjectInput, UpdateProjectInput, ProjectFilters } from "@/schemas/project";
import { TRPCError } from "@trpc/server";

export const projectRouter = router({
  list: protectedProcedure
    .input(ProjectFilters)
    .query(async ({ ctx, input }) => {
      const { cursor, limit, search, visibility } = input;

      const projects = await ctx.prisma.project.findMany({
        where: {
          teamId: ctx.user.teamId,
          ...(visibility && { visibility }),
          ...(search && {
            name: { contains: search, mode: "insensitive" },
          }),
        },
        take: limit + 1,        // Fetch one extra to detect "has next page"
        ...(cursor && {
          cursor: { id: cursor },
          skip: 1,               // Skip the cursor item itself
        }),
        orderBy: { createdAt: "desc" },
        include: {
          _count: { select: { tasks: true } },  // Task count without fetching tasks
        },
      });

      // Cursor-based pagination: if we got limit+1 items, there's a next page
      let nextCursor: string | undefined;
      if (projects.length > limit) {
        const nextItem = projects.pop();
        nextCursor = nextItem?.id;
      }

      return { projects, nextCursor };
    }),

  create: protectedProcedure
    .input(CreateProjectInput)
    .mutation(async ({ ctx, input }) => {
      // Check team project limit before creating
      const projectCount = await ctx.prisma.project.count({
        where: { teamId: ctx.user.teamId },
      });

      if (projectCount >= 50) {
        throw new TRPCError({
          code: "FORBIDDEN",
          message: "Team project limit reached (50). Archive unused projects to create new ones.",
        });
      }

      return ctx.prisma.project.create({
        data: {
          ...input,
          teamId: ctx.user.teamId,
          createdById: ctx.user.id,
        },
      });
    }),

  update: protectedProcedure
    .input(UpdateProjectInput)
    .mutation(async ({ ctx, input }) => {
      const { id, ...data } = input;

      // Verify the user's team owns this project
      const existing = await ctx.prisma.project.findUnique({
        where: { id },
        select: { teamId: true },
      });

      if (!existing || existing.teamId !== ctx.user.teamId) {
        throw new TRPCError({ code: "NOT_FOUND", message: "Project not found" });
      }

      return ctx.prisma.project.update({ where: { id }, data });
    }),
});

// src/lib/trpc-client.ts — tRPC React client setup.
// httpBatchLink combines multiple simultaneous requests into a single HTTP call,
// reducing network overhead when a page loads several queries at once.

import { createTRPCReact } from "@trpc/react-query";
import { httpBatchLink, loggerLink } from "@trpc/client";
import superjson from "superjson";
import type { AppRouter } from "@/server/routers/_app";

export const trpc = createTRPCReact<AppRouter>();

export function getTRPCClient() {
  return trpc.createClient({
    links: [
      loggerLink({
        enabled: (opts) =>
          process.env.NODE_ENV === "development" ||
          (opts.direction === "down" && opts.result instanceof Error),
      }),
      httpBatchLink({
        url: "/api/trpc",
        transformer: superjson,
      }),
    ],
  });
}

// src/components/ProjectList.tsx — Project list with infinite scroll.
// The trpc hook returns fully typed data — hover over `project.name`
// and TypeScript knows it's a string between 3-100 characters.

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

export function ProjectList({ search }: { search?: string }) {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isLoading,
  } = trpc.project.list.useInfiniteQuery(
    { limit: 20, search },
    {
      getNextPageParam: (lastPage) => lastPage.nextCursor,
      staleTime: 30_000,  // 30 seconds before background refetch
    },
  );

  const projects = data?.pages.flatMap((page) => page.projects) ?? [];

  if (isLoading) return <ProjectListSkeleton />;

  return (
    <div className="space-y-3">
      {projects.map((project) => (
        <ProjectCard
          key={project.id}
          name={project.name}
          taskCount={project._count.tasks}
          color={project.color}
        />
      ))}
      {hasNextPage && (
        <button onClick={() => fetchNextPage()}>Load more</button>
      )}
    </div>
  );
}

// src/hooks/useCreateProject.ts — Optimistic mutation with rollback.
// The cache is updated instantly, giving the user sub-10ms feedback.
// If the server returns an error, onError restores the previous state.

import { trpc } from "@/lib/trpc-client";
import type { CreateProjectInput } from "@/schemas/project";

export function useCreateProject() {
  const utils = trpc.useUtils();

  return trpc.project.create.useMutation({
    onMutate: async (newProject: CreateProjectInput) => {
      // Cancel outgoing refetches so they don't overwrite our optimistic update
      await utils.project.list.cancel();

      // Snapshot current cache for potential rollback
      const previousData = utils.project.list.getInfiniteData({ limit: 20 });

      // Optimistically insert the new project at the top of the list
      utils.project.list.setInfiniteData({ limit: 20 }, (old) => {
        if (!old) return old;
        const optimisticProject = {
          id: `temp-${Date.now()}`,  // Temporary ID, replaced on server response
          ...newProject,
          createdAt: new Date(),
          _count: { tasks: 0 },
        };
        return {
          ...old,
          pages: [
            {
              projects: [optimisticProject, ...old.pages[0].projects],
              nextCursor: old.pages[0].nextCursor,
            },
            ...old.pages.slice(1),
          ],
        };
      });

      return { previousData };
    },

    onError: (_err, _newProject, context) => {
      // Rollback to the snapshot if the mutation fails
      if (context?.previousData) {
        utils.project.list.setInfiniteData({ limit: 20 }, context.previousData);
      }
    },

    onSettled: () => {
      // Refetch after mutation to sync with server state
      utils.project.list.invalidate();
    },
  });
}