server-setup

# tRPC -- Server Setup ## Setup ```ts // server/trpc.ts import { initTRPC } from '@trpc/server'; const t = initTRPC.create(); export const router = t.router; export const publicProcedure = t.procedure; ``` ```ts // server/appRouter.ts import { z } from 'zod'; import { publicProcedure, router } from './trpc'; type User = { id: string; name: string }; export const appRouter = router({ userList: publicProcedure.query(async (): Promise<User[]> => { return [{ id: '1', name: 'Katt' }]; }), userById: publicProcedure .input(z.string()) .query(async ({ input }): Promise<User> => { return { id: input, name: 'Katt' }; }), userCreate: publicProcedure .input(z.object({ name: z.string() })) .mutation(async ({ input }): Promise<User> => { return { id: '1', ...input }; }), }); export type AppRouter = typeof appRouter; ``` ```ts // server/index.ts import { createHTTPServer } from '@trpc/server/adapters/standalone'; import { appRouter } from './appRouter'; const server = createHTTPServer({ router: appRouter }); server.listen(3000); ``` ## Core Patterns ### Context with typed session ```ts // server/context.ts import type { CreateHTTPContextOptions } from '@trpc/server/adapters/standalone'; export async function createContext(opts: CreateHTTPContextOptions) { const token = opts.req.headers['authorization']; return { token }; } export type Context = Awaited<ReturnType<typeof createContext>>; ``` ```ts // server/trpc.ts import { initTRPC } from '@trpc/server'; import type { Context } from './context'; const t = initTRPC.context<Context>().create(); export const router = t.router; export const publicProcedure = t.procedure; ``` ```ts // server/index.ts import { createHTTPServer } from '@trpc/server/adapters/standalone'; import { appRouter } from './appRouter'; import { createContext } from './context'; const server = createHTTPServer({ router: appRouter, createContext, }); server.listen(3000); ``` ### Inner/outer context split for testability ```ts // server/context.ts import type { CreateHTTPContextOptions } from '@trpc/server/adapters/standalone'; import { db } from './db'; interface CreateInnerContextOptions { session: { user: { email: string } } | null; } export async function createContextInner(opts?: CreateInnerContextOptions) { return { db, session: opts?.session ?? null, }; } export async function createContext(opts: CreateHTTPContextOptions) { const session = getSessionFromCookie(opts.req); const contextInner = await createContextInner({ session }); return { ...contextInner, req: opts.req, res: opts.res, }; } export type Context = Awaited<ReturnType<typeof createContextInner>>; ``` Infer `Context` from `createContextInner` so server-side callers and tests never need HTTP request objects. ### Merging child routers ```ts // server/routers/user.ts import { publicProcedure, router } from '../trpc'; export const userRouter = router({ list: publicProcedure.query(() => []), }); ``` ```ts // server/routers/post.ts import { z } from 'zod'; import { publicProcedure, router } from '../trpc'; export const postRouter = router({ create: publicProcedure .input(z.object({ title: z.string() })) .mutation(({ input }) => ({ id: '1', ...input })), list: publicProcedure.query(() => []), }); ``` ```ts // server/routers/_app.ts import { router } from '../trpc'; import { postRouter } from './post'; import { userRouter } from './user'; export const appRouter = router({ user: userRouter, post: postRouter, }); export type AppRouter = typeof appRouter; ``` ### Lazy-loaded routers for serverless cold starts ```ts // server/routers/_app.ts import { lazy } from '@trpc/server'; import { router } from '../trpc'; export const appRouter = router({ // Short-hand when the module has exactly one router exported greeting: lazy(() => import('./greeting.js')), // Use .then() to pick a named export when the module exports multiple routers user: lazy(() => import('./user.js').then((m) => m.userRouter)), }); export type AppRouter = typeof appRouter; ``` ## Common Mistakes ### [CRITICAL] Calling initTRPC.create() more than once Wrong: ```ts // file: userRouter.ts import { initTRPC } from '@trpc/server'; const t = initTRPC.create(); export const userRouter = t.router({}); // file: postRouter.ts import { initTRPC } from '@trpc/server'; const t2 = initTRPC.create(); export const postRouter = t2.router({}); ``` Correct: ```ts // file: trpc.ts (single file, created once) import { initTRPC } from '@trpc/server'; import type { Context } from './context'; const t = initTRPC.context<Context>().create(); export const router = t.router; export const publicProcedure = t.procedure; ``` Multiple tRPC instances cause type mismatches and runtime errors when routers from different instances are merged. Source: www/docs/server/routers.md ### [HIGH] Using reserved words as procedure names Wrong: ```ts import { publicProcedure, router } from './trpc'; const appRouter = router({ then: publicProcedure.query(() => 'hello'), }); ``` Correct: ```ts import { publicProcedure, router } from './trpc'; const appRouter = router({ next: publicProcedure.query(() => 'hello'), }); ``` Router creation throws if procedure names are "then", "call", or "apply" because these conflict with JavaScript Proxy internals. Source: packages/server/src/unstable-core-do-not-import/router.ts ### [CRITICAL] Importing AppRouter as a value import Wrong: ```ts // client.ts import { AppRouter } from '../server/router'; ``` Correct: ```ts // client.ts import type { AppRouter } from '../server/router'; ``` A non-type import pulls the entire server bundle into the client; use `import type` so it is stripped at build time. Source: www/docs/server/routers.md ### [MEDIUM] Creating context without inner/outer split Wrong: ```ts import type { CreateExpressContextOptions } from '@trpc/server/adapters/express'; export function createContext({ req }: CreateExpressContextOptions) { return { db: prisma, user: getUserFromReq(req) }; } ``` Correct: ```ts import type { CreateExpressContextOptions } from '@trpc/server/adapters/express'; export function createContextInner(opts: { user?: User }) { return { db: prisma, user: opts.user ?? null }; } export function createContext({ req }: CreateExpressContextOptions) { return createContextInner({ user: getUserFromReq(req) }); } ``` Without an inner context factory, server-side callers and tests must construct HTTP request objects to get context. Source: www/docs/server/context.md ### [HIGH] Merging routers with different transformers Wrong: ```ts import { initTRPC } from '@trpc/server'; import superjson from 'superjson'; const t1 = initTRPC.create({ transformer: superjson }); const t2 = initTRPC.create(); const router1 = t1.router({ a: t1.procedure.query(() => 'a') }); const router2 = t2.router({ b: t2.procedure.query(() => 'b') }); t1.mergeRouters(router1, router2); ``` Correct: ```ts import { initTRPC } from '@trpc/server'; import superjson from 'superjson'; const t = initTRPC.create({ transformer: superjson }); const router1 = t.router({ a: t.procedure.query(() => 'a') }); const router2 = t.router({ b: t.procedure.query(() => 'b') }); t.mergeRouters(router1, router2); ``` `t.mergeRouters()` throws at runtime if the routers were created with different transformer or errorFormatter configurations. Source: packages/server/src/unstable-core-do-not-import/router.ts ### [CRITICAL] Importing appRouter value into client code Wrong: ```ts // client.ts import { appRouter } from '../server/router'; type AppRouter = typeof appRouter; ``` Correct: ```ts // client.ts import type { AppRouter } from '../server/router'; // server/router.ts export type AppRouter = typeof appRouter; ``` Importing the appRouter value bundles the entire server into the client, even if you only use `typeof`. Source: www/docs/server/routers.md ## See Also - `middlewares` -- add auth, logging, context extension to procedures - `validators` -- add input/output validation with Zod - `error-handling` -- throw and format typed errors - `server-side-calls` -- call procedures from server code - `adapter-standalone` -- mount on Node.js HTTP server - `adapter-fetch` -- mount on edge runtimes