CRUD

Add a complete feature to Init: database table → API router → UI. The todo feature is the reference implementation - this guide builds a post feature the same way. Copy the pattern, rename the nouns.

The full path touches three packages:

packages/db/src/drizzle-schema.ts        # 1. Table
packages/api/src/post/post-schema.ts     # 2. Zod inputs
packages/api/src/post/post-router.ts     # 3. Procedures
packages/api/src/root-router.ts          # 4. Mount
apps/web/src/app/.../posts/page.tsx      # 5. Server page
apps/web/src/app/.../posts/_components/  # 6. Client UI

1. Define the Table

// packages/db/src/drizzle-schema.ts
export const post = pgTable(
  "post",
  (t) => ({
    id: t.uuid().notNull().primaryKey().defaultRandom(),
    organizationId: t
      .text()
      .notNull()
      .references(() => organization.id, { onDelete: "cascade" }),
    title: t.text().notNull(),
    content: t.text(),
    createdAt: t.timestamp({ withTimezone: true }).notNull().defaultNow(),
    updatedAt: t.timestamp({ withTimezone: true }).notNull().defaultNow(),
  }),
  (table) => [index("post_organization_id_idx").on(table.organizationId)],
).enableRLS();

export const postRelations = relations(post, ({ one }) => ({
  organization: one(organization, {
    fields: [post.organizationId],
    references: [organization.id],
  }),
}));

Every rule here matters: organizationId scopes the data to a tenant, the index makes the list query fast, cascade cleans up when an org is deleted, .enableRLS() keeps PostgREST locked out. See Data Modelling for why.

2. Push the Schema

pnpm db:push

No migration files, no codegen. Types flow from the schema definition immediately.

3. Validate Inputs

// packages/api/src/post/post-schema.ts
import { z } from "zod";

export const createPostInput = z.object({
  title: z.string().trim().min(1, "Title is required").max(255),
  content: z.string().optional(),
});

export const deletePostInput = z.object({
  id: z.uuid(),
});

The organization slug and the membership check come from organizationProcedure (next step), which merges its own { slug } input with these - so each schema carries only the post's own fields.

4. Write the Router

// packages/api/src/post/post-router.ts
import { post } from "@repo/db/drizzle-schema";
import { TRPCError } from "@trpc/server";
import { and, eq } from "drizzle-orm";

import { createTRPCRouter, organizationProcedure } from "../trpc";
import { createPostInput, deletePostInput } from "./post-schema";

export const postRouter = createTRPCRouter({
  list: organizationProcedure.query(async ({ ctx }) => {
    const posts = await ctx.db.query.post.findMany({
      where: (postTable, { eq }) => eq(postTable.organizationId, ctx.organization.id),
      orderBy: (postTable, { desc }) => desc(postTable.createdAt),
    });

    return { posts };
  }),
  create: organizationProcedure.input(createPostInput).mutation(async ({ ctx, input }) => {
    const [createdPost] = await ctx.db
      .insert(post)
      .values({
        organizationId: ctx.organization.id,
        title: input.title,
        content: input.content,
      })
      .returning();

    return { post: createdPost };
  }),
  delete: organizationProcedure.input(deletePostInput).mutation(async ({ ctx, input }) => {
    const [deletedPost] = await ctx.db
      .delete(post)
      .where(and(eq(post.id, input.id), eq(post.organizationId, ctx.organization.id)))
      .returning();

    if (!deletedPost) {
      throw new TRPCError({ code: "NOT_FOUND", message: "Post not found" });
    }

    return { post: deletedPost };
  }),
});

organizationProcedure (in packages/api/src/trpc.ts) takes the slug, resolves the org, and proves membership before any handler runs - list needs no .input() at all, and handlers read ctx.organization.id. Every mutation still filters by organizationId in the where clause, so a valid member of org A can never touch org B's rows.

5. Mount the Router

// packages/api/src/root-router.ts
export const appRouter = createTRPCRouter({
  waitlist: waitlistRouter,
  organization: organizationRouter,
  todo: todoRouter,
  post: postRouter, // Add here
});

trpc.post.* now autocompletes in every app.

6. Build the Page

Server component: check the session, prefetch the query, hydrate.

// apps/web/src/app/(dashboard)/dashboard/[slug]/posts/page.tsx
import { redirect } from "next/navigation";
import { getSession } from "@repo/api/auth/auth";

import { PageHeader } from "@/components/header";
import { HydrateClient, prefetch, trpc } from "@/trpc/server";
import { PostList } from "./_components/post-list";

const Page = async (props: { params: Promise<{ slug: string }> }) => {
  const { slug } = await props.params;

  const session = await getSession();
  if (!session) {
    return redirect(`/auth/login?nextPath=/dashboard/${slug}/posts`);
  }

  prefetch(trpc.post.list.queryOptions({ slug }));

  return (
    <HydrateClient>
      <main className="flex flex-1 flex-col px-5 pb-5">
        <PageHeader>Posts</PageHeader>
        <PostList slug={slug} />
      </main>
    </HydrateClient>
  );
};

export default Page;

7. Build the Client Component

// apps/web/src/app/(dashboard)/dashboard/[slug]/posts/_components/post-list.tsx
"use client";

import { toast } from "@repo/ui/components/sonner";
import { useMutation, useQueryClient, useSuspenseQuery } from "@tanstack/react-query";

import { useTRPC } from "@/trpc/react";

export const PostList = ({ slug }: { slug: string }) => {
  const trpc = useTRPC();
  const queryClient = useQueryClient();

  // Resolves instantly from the server prefetch - no loading spinner
  const { data } = useSuspenseQuery(trpc.post.list.queryOptions({ slug }));

  // Refetch this org's list after a write - each mutation invalidates only
  // what it touched; there's no global invalidate-everything net behind it
  const invalidatePosts = () => queryClient.invalidateQueries(trpc.post.list.queryFilter({ slug }));

  const createPost = useMutation(
    trpc.post.create.mutationOptions({
      onError: (error) => toast.error(error.message),
      onSuccess: invalidatePosts,
    }),
  );

  return (
    <ul>
      {data.posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
};

The full reference - inline editing, delete confirmation, per-row pending states - is apps/web/src/app/(dashboard)/dashboard/[slug]/(home)/_components/todo-list.tsx.

8. Test It

Routers test without a database. createCallerFactory plus the mock context from packages/api/src/test-utils.ts:

// packages/api/src/post/post-router.test.ts
import { describe, expect, it } from "vitest";

import { createMockContext } from "../test-utils";
import { createCallerFactory } from "../trpc";
import { postRouter } from "./post-router";

const createCaller = createCallerFactory(postRouter);

it("throws UNAUTHORIZED when user is not a member", async () => {
  const ctx = createMockContext();
  ctx.db.query.organization.findFirst.mockResolvedValue({ id: "org-1", slug: "acme" });
  ctx.db.query.member.findFirst.mockResolvedValue(undefined);

  const caller = createCaller(ctx);
  await expect(caller.list({ slug: "acme" })).rejects.toThrow();
});

pnpm -F @repo/api test

packages/api/src/todo/todo-router.test.ts covers the full matrix: happy paths, missing org, non-member, not-found rows.

Ship It Everywhere

Nothing else to do. The mobile app (apps/mobile/src/utils/api.tsx) consumes the same AppRouter type, so trpc.post.list works there too. The extension iframes the web app and gets the feature for free.

Checklist

Table has organizationId + index + .enableRLS()
pnpm db:push ran
Zod schema validates the feature's own fields; slug comes from organizationProcedure
Router uses organizationProcedure and filters mutations by organizationId
Router mounted in root-router.ts
Page prefetches; client uses useSuspenseQuery
Tests cover the unauthorized paths

Next Steps

Data fetching - Queries in depth
Data mutations - Mutations in depth
API reference - tRPC architecture

On this page