{"id":"abbec752-9eee-4cc1-93fb-26340af72697","shortId":"nLJtVj","kind":"skill","title":"trpc-fullstack","tagline":"Build end-to-end type-safe APIs with tRPC — routers, procedures, middleware, subscriptions, and Next.js/React integration patterns.","description":"# tRPC Full-Stack\n\n## Overview\n\ntRPC lets you build fully type-safe APIs without writing a schema or code-generation step. Your TypeScript types flow from the server router directly to the client — so every API call is autocompleted, validated at compile time, and refactoring-safe. Use this skill when building TypeScript monorepos, Next.js apps, or any project where the server and client share a codebase.\n\n## When to Use This Skill\n\n- Use when building a TypeScript full-stack app (Next.js, Remix, Express + React) where the client and server share a single repo\n- Use when you want end-to-end type safety on API calls without REST/GraphQL schema overhead\n- Use when adding real-time features (subscriptions) to an existing tRPC setup\n- Use when designing multi-step middleware (auth, rate limiting, tenant scoping) on tRPC procedures\n- Use when migrating an existing REST/GraphQL API to tRPC incrementally\n\n## Core Concepts\n\n### Routers and Procedures\n\nA **router** groups related **procedures** (think: endpoints). Procedures are typed functions — `query` for reads, `mutation` for writes, `subscription` for real-time streams.\n\n### Input Validation with Zod\n\nAll procedure inputs are validated with Zod schemas. The validated, typed input is available in the procedure handler — no manual parsing.\n\n### Context\n\n`context` is shared state passed to every procedure — auth session, database client, request headers, etc. It is built once per request in a context factory. **Important:** Next.js App Router and Pages Router require separate context factories because App Router handlers receive a fetch `Request`, not a Node.js `NextApiRequest`.\n\n### Middleware\n\nMiddleware chains run before a procedure. Use them for authentication, logging, and request enrichment. They can extend the context for downstream procedures.\n\n---\n\n## How It Works\n\n### Step 1: Install and Initialize\n\n```bash\nnpm install @trpc/server @trpc/client @trpc/react-query @tanstack/react-query zod\n```\n\nCreate the tRPC instance and reusable builders:\n\n```typescript\n// src/server/trpc.ts\nimport { initTRPC, TRPCError } from '@trpc/server';\nimport { type Context } from './context';\nimport { ZodError } from 'zod';\n\nconst t = initTRPC.context().create({\n errorFormatter({ shape, error }) {\n return {\n ...shape,\n data: {\n ...shape.data,\n zodError:\n error.cause instanceof ZodError ? error.cause.flatten() : null,\n },\n };\n },\n});\n\nexport const router = t.router;\nexport const publicProcedure = t.procedure;\nexport const middleware = t.middleware;\n```\n\n### Step 2: Define Two Context Factories\n\nNext.js App Router handlers receive a fetch `Request` (not a Node.js `NextApiRequest`), so the context\nmust be built differently depending on the call site. Define one factory per surface:\n\n```typescript\n// src/server/context.ts\nimport { type FetchCreateContextFnOptions } from '@trpc/server/adapters/fetch';\nimport { auth } from '@/server/auth'; // Next-Auth v5 / your auth helper\nimport { db } from './db';\n\n/**\n * Context for the HTTP handler (App Router Route Handler).\n * `opts.req` is the fetch Request — auth is resolved server-side via `auth()`.\n */\nexport async function createTRPCContext(opts: FetchCreateContextFnOptions) {\n const session = await auth(); // server-side auth — no req/res needed\n return { session, db, headers: opts.req.headers };\n}\n\n/**\n * Context for direct server-side callers (Server Components, RSC, cron jobs).\n * No HTTP request is involved, so we call auth() directly from the server.\n */\nexport async function createServerContext() {\n const session = await auth();\n return { session, db };\n}\n\nexport type Context = Awaited>;\n```\n\n### Step 3: Build an Auth Middleware and Protected Procedure\n\n```typescript\n// src/server/trpc.ts (continued)\nconst enforceAuth = middleware(({ ctx, next }) => {\n if (!ctx.session?.user) {\n throw new TRPCError({ code: 'UNAUTHORIZED' });\n }\n return next({\n ctx: {\n // Narrows type: session is non-null from here\n session: { ...ctx.session, user: ctx.session.user },\n },\n });\n});\n\nexport const protectedProcedure = t.procedure.use(enforceAuth);\n```\n\n### Step 4: Create Routers\n\n```typescript\n// src/server/routers/post.ts\nimport { z } from 'zod';\nimport { router, publicProcedure, protectedProcedure } from '../trpc';\nimport { TRPCError } from '@trpc/server';\n\nexport const postRouter = router({\n list: publicProcedure\n .input(\n z.object({\n limit: z.number().min(1).max(100).default(20),\n cursor: z.string().optional(),\n })\n )\n .query(async ({ ctx, input }) => {\n const posts = await ctx.db.post.findMany({\n take: input.limit + 1,\n cursor: input.cursor ? { id: input.cursor } : undefined,\n orderBy: { createdAt: 'desc' },\n });\n const nextCursor =\n posts.length > input.limit ? posts.pop()!.id : undefined;\n return { posts, nextCursor };\n }),\n\n byId: publicProcedure\n .input(z.object({ id: z.string() }))\n .query(async ({ ctx, input }) => {\n const post = await ctx.db.post.findUnique({ where: { id: input.id } });\n if (!post) throw new TRPCError({ code: 'NOT_FOUND' });\n return post;\n }),\n\n create: protectedProcedure\n .input(\n z.object({\n title: z.string().min(1).max(200),\n body: z.string().min(1),\n })\n )\n .mutation(async ({ ctx, input }) => {\n return ctx.db.post.create({\n data: { ...input, authorId: ctx.session.user.id },\n });\n }),\n\n delete: protectedProcedure\n .input(z.object({ id: z.string() }))\n .mutation(async ({ ctx, input }) => {\n const post = await ctx.db.post.findUnique({ where: { id: input.id } });\n if (!post) throw new TRPCError({ code: 'NOT_FOUND' });\n if (post.authorId !== ctx.session.user.id)\n throw new TRPCError({ code: 'FORBIDDEN' });\n return ctx.db.post.delete({ where: { id: input.id } });\n }),\n});\n```\n\n### Step 5: Compose the Root Router and Export Types\n\n```typescript\n// src/server/root.ts\nimport { router } from './trpc';\nimport { postRouter } from './routers/post';\nimport { userRouter } from './routers/user';\n\nexport const appRouter = router({\n post: postRouter,\n user: userRouter,\n});\n\n// Export the type for the client — never import the appRouter itself on the client\nexport type AppRouter = typeof appRouter;\n```\n\n### Step 6: Mount the API Handler (Next.js App Router)\n\nThe App Router handler must use `fetchRequestHandler` and the **fetch-based** context factory.\n`createTRPCContext` receives `FetchCreateContextFnOptions` (with a fetch `Request`), not\na Pages Router `req/res` pair.\n\n```typescript\n// src/app/api/trpc/[trpc]/route.ts\nimport { fetchRequestHandler } from '@trpc/server/adapters/fetch';\nimport { type FetchCreateContextFnOptions } from '@trpc/server/adapters/fetch';\nimport { appRouter } from '@/server/root';\nimport { createTRPCContext } from '@/server/context';\n\nconst handler = (req: Request) =>\n fetchRequestHandler({\n endpoint: '/api/trpc',\n req,\n router: appRouter,\n // opts is FetchCreateContextFnOptions — req is the fetch Request\n createContext: (opts: FetchCreateContextFnOptions) => createTRPCContext(opts),\n });\n\nexport { handler as GET, handler as POST };\n```\n\n### Step 7: Set Up the Client (React Query)\n\n```typescript\n// src/utils/trpc.ts\nimport { createTRPCReact } from '@trpc/react-query';\nimport type { AppRouter } from '@/server/root';\n\nexport const trpc = createTRPCReact();\n```\n\n```typescript\n// src/app/providers.tsx\n'use client';\nimport { QueryClient, QueryClientProvider } from '@tanstack/react-query';\nimport { httpBatchLink } from '@trpc/client';\nimport { useState } from 'react';\nimport { trpc } from '@/utils/trpc';\n\nexport function TRPCProvider({ children }: { children: React.ReactNode }) {\n const [queryClient] = useState(() => new QueryClient());\n const [trpcClient] = useState(() =>\n trpc.createClient({\n links: [\n httpBatchLink({\n url: '/api/trpc',\n headers: () => ({ 'x-trpc-source': 'react' }),\n }),\n ],\n })\n );\n\n return (\n \n {children}\n \n );\n}\n```\n\n---\n\n## Examples\n\n### Example 1: Fetching Data in a Component\n\n```typescript\n// components/PostList.tsx\n'use client';\nimport { trpc } from '@/utils/trpc';\n\nexport function PostList() {\n const { data, isLoading, error } = trpc.post.list.useQuery({ limit: 10 });\n\n if (isLoading) return

Loading…

;\n if (error) return

Error: {error.message}

;\n\n return (\n
    \n {data?.posts.map((post) => (\n
  • {post.title}
    • \n ))}\n
\n );\n}\n```\n\n### Example 2: Mutation with Cache Invalidation\n\n```typescript\n'use client';\nimport { trpc } from '@/utils/trpc';\n\nexport function CreatePost() {\n const utils = trpc.useUtils();\n\n const createPost = trpc.post.create.useMutation({\n onSuccess: () => {\n // Invalidate and refetch the post list\n utils.post.list.invalidate();\n },\n });\n\n const handleSubmit = (e: React.FormEvent) => {\n e.preventDefault();\n const form = e.currentTarget;\n const data = new FormData(form);\n createPost.mutate({\n title: data.get('title') as string,\n body: data.get('body') as string,\n });\n form.reset();\n };\n\n return (\n
\n \n