@trpc/server 11.14.0 → 11.14.1

package/skills/caching/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: caching
+description: >
+  Set HTTP cache headers on tRPC query responses via responseMeta callback for
+  CDN and browser caching. Configure Cache-Control, s-maxage,
+  stale-while-revalidate. Handle caching with batching and authenticated requests.
+  Avoid caching mutations, errors, and authenticated responses.
+type: core
+library: trpc
+library_version: '11.14.0'
+requires:
+  - server-setup
+sources:
+  - 'trpc/trpc:www/docs/server/caching.md'
+---
+
+# tRPC -- Caching
+
+## Setup
+
+```ts
+// server/trpc.ts
+import { initTRPC } from '@trpc/server';
+import type { CreateHTTPContextOptions } from '@trpc/server/adapters/standalone';
+
+export const createContext = async (opts: CreateHTTPContextOptions) => {
+  return {
+    req: opts.req,
+    res: opts.res,
+    user: null as { id: string } | null,
+  };
+};
+
+type Context = Awaited<ReturnType<typeof createContext>>;
+
+export const t = initTRPC.context<Context>().create();
+export const router = t.router;
+export const publicProcedure = t.procedure;
+```
+
+```ts
+// server/appRouter.ts
+import { publicProcedure, router } from './trpc';
+
+export const appRouter = router({
+  public: router({
+    slowQueryCached: publicProcedure.query(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 5000));
+      return { lastUpdated: new Date().toJSON() };
+    }),
+  }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+```ts
+// server/index.ts
+import { createHTTPServer } from '@trpc/server/adapters/standalone';
+import { appRouter } from './appRouter';
+import { createContext } from './trpc';
+
+const server = createHTTPServer({
+  router: appRouter,
+  createContext,
+  responseMeta(opts) {
+    const { paths, errors, type } = opts;
+
+    const allPublic =
+      paths && paths.every((path) => path.startsWith('public.'));
+    const allOk = errors.length === 0;
+    const isQuery = type === 'query';
+
+    if (allPublic && allOk && isQuery) {
+      const ONE_DAY_IN_SECONDS = 60 * 60 * 24;
+      return {
+        headers: new Headers([
+          [
+            'cache-control',
+            `s-maxage=1, stale-while-revalidate=${ONE_DAY_IN_SECONDS}`,
+          ],
+        ]),
+      };
+    }
+    return {};
+  },
+});
+
+server.listen(3000);
+```
+
+## Core Patterns
+
+### Path-based public route caching
+
+```ts
+import { createHTTPServer } from '@trpc/server/adapters/standalone';
+import { appRouter } from './appRouter';
+import { createContext } from './trpc';
+
+const server = createHTTPServer({
+  router: appRouter,
+  createContext,
+  responseMeta({ paths, errors, type }) {
+    const allPublic =
+      paths && paths.every((path) => path.startsWith('public.'));
+    const allOk = errors.length === 0;
+    const isQuery = type === 'query';
+
+    if (allPublic && allOk && isQuery) {
+      return {
+        headers: new Headers([
+          ['cache-control', 's-maxage=1, stale-while-revalidate=86400'],
+        ]),
+      };
+    }
+    return {};
+  },
+});
+```
+
+Name public routes with a `public` prefix (e.g., `public.slowQueryCached`) so `responseMeta` can identify them by path.
+
+### Skip caching for authenticated requests
+
+```ts
+import { createHTTPServer } from '@trpc/server/adapters/standalone';
+import { appRouter } from './appRouter';
+import { createContext } from './trpc';
+
+const server = createHTTPServer({
+  router: appRouter,
+  createContext,
+  responseMeta({ ctx, errors, type }) {
+    if (ctx?.user || errors.length > 0 || type !== 'query') {
+      return {};
+    }
+    return {
+      headers: new Headers([
+        ['cache-control', 's-maxage=1, stale-while-revalidate=86400'],
+      ]),
+    };
+  },
+});
+```
+
+## Common Mistakes
+
+### [CRITICAL] Caching authenticated responses
+
+Wrong:
+
+```ts
+import { createHTTPServer } from '@trpc/server/adapters/standalone';
+import { appRouter } from './appRouter';
+
+const server = createHTTPServer({
+  router: appRouter,
+  responseMeta() {
+    return {
+      headers: new Headers([['cache-control', 's-maxage=60']]),
+    };
+  },
+});
+```
+
+Correct:
+
+```ts
+import { createHTTPServer } from '@trpc/server/adapters/standalone';
+import { appRouter } from './appRouter';
+import { createContext } from './trpc';
+
+const server = createHTTPServer({
+  router: appRouter,
+  createContext,
+  responseMeta({ ctx, errors, type }) {
+    if (ctx?.user || errors.length > 0 || type !== 'query') {
+      return {};
+    }
+    return {
+      headers: new Headers([
+        ['cache-control', 's-maxage=1, stale-while-revalidate=86400'],
+      ]),
+    };
+  },
+});
+```
+
+With batching enabled by default, a cached response containing personal data could be served to other users; always check for auth context, errors, and request type before setting cache headers.
+
+Source: www/docs/server/caching.md
+
+### [HIGH] Next.js App Router overrides Cache-Control headers
+
+There is no code fix for this -- Next.js App Router overrides `Cache-Control` headers set by tRPC via `responseMeta`. The documented caching approach using `responseMeta` does not work as expected in App Router. Use Next.js native caching mechanisms (`revalidate`, `unstable_cache`) instead when deploying on App Router.
+
+Source: https://github.com/trpc/trpc/issues/5625
+
+## See Also
+
+- `server-setup` -- initTRPC, createContext configuration
+- `adapter-standalone` -- responseMeta option on createHTTPServer
+- `adapter-fetch` -- responseMeta option on fetchRequestHandler
+- `links` -- splitLink to separate public/private requests on the client

package/skills/error-handling/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: error-handling
+description: >
+  Throw typed errors with TRPCError and error codes (NOT_FOUND, UNAUTHORIZED,
+  BAD_REQUEST, INTERNAL_SERVER_ERROR), configure errorFormatter for client-side
+  Zod error display, handle errors globally with onError callback, map tRPC errors
+  to HTTP status codes with getHTTPStatusCodeFromError().
+type: core
+library: trpc
+library_version: '11.14.0'
+requires:
+  - server-setup
+sources:
+  - 'trpc/trpc:www/docs/server/error-handling.md'
+  - 'trpc/trpc:www/docs/server/error-formatting.md'
+  - 'trpc/trpc:packages/server/src/unstable-core-do-not-import/error/TRPCError.ts'
+---
+
+# tRPC -- Error Handling
+
+## Setup
+
+```ts
+// server/trpc.ts
+import { initTRPC } from '@trpc/server';
+import { ZodError } from 'zod';
+
+const t = initTRPC.create({
+  errorFormatter({ shape, error }) {
+    return {
+      ...shape,
+      data: {
+        ...shape.data,
+        zodError:
+          error.code === 'BAD_REQUEST' && error.cause instanceof ZodError
+            ? error.cause.flatten()
+            : null,
+      },
+    };
+  },
+});
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+```
+
+## Core Patterns
+
+### Throwing typed errors from procedures
+
+```ts
+import { TRPCError } from '@trpc/server';
+import { z } from 'zod';
+import { publicProcedure, router } from './trpc';
+
+export const appRouter = router({
+  userById: publicProcedure
+    .input(z.object({ id: z.string() }))
+    .query(({ input }) => {
+      const user = getUserFromDb(input.id);
+      if (!user) {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: `User with id ${input.id} not found`,
+        });
+      }
+      return user;
+    }),
+});
+
+function getUserFromDb(id: string) {
+  if (id === '1') return { id: '1', name: 'Katt' };
+  return null;
+}
+```
+
+### Wrapping original errors with cause
+
+```ts
+import { TRPCError } from '@trpc/server';
+import { publicProcedure, router } from './trpc';
+
+export const appRouter = router({
+  riskyOperation: publicProcedure.mutation(async () => {
+    try {
+      return await externalService();
+    } catch (err) {
+      throw new TRPCError({
+        code: 'INTERNAL_SERVER_ERROR',
+        message: 'An unexpected error occurred, please try again later.',
+        cause: err,
+      });
+    }
+  }),
+});
+
+async function externalService() {
+  throw new Error('connection refused');
+}
+```
+
+Pass the original error as `cause` to retain the stack trace for debugging.
+
+### Global error handling with onError
+
+```ts
+import { createHTTPServer } from '@trpc/server/adapters/standalone';
+import { appRouter } from './appRouter';
+
+const server = createHTTPServer({
+  router: appRouter,
+  onError(opts) {
+    const { error, type, path, input, ctx, req } = opts;
+    console.error('Error:', error);
+    if (error.code === 'INTERNAL_SERVER_ERROR') {
+      // send to bug reporting service
+    }
+  },
+});
+
+server.listen(3000);
+```
+
+### Extracting HTTP status from TRPCError
+
+```ts
+import { TRPCError } from '@trpc/server';
+import { getHTTPStatusCodeFromError } from '@trpc/server/http';
+
+function handleError(error: unknown) {
+  if (error instanceof TRPCError) {
+    const httpCode = getHTTPStatusCodeFromError(error);
+    console.log(httpCode); // e.g., 400, 401, 404, 500
+  }
+}
+```
+
+## Common Mistakes
+
+### [HIGH] Throwing plain Error instead of TRPCError
+
+Wrong:
+
+```ts
+import { publicProcedure } from './trpc';
+
+const proc = publicProcedure.query(() => {
+  throw new Error('Not found');
+  // client receives 500 INTERNAL_SERVER_ERROR
+});
+```
+
+Correct:
+
+```ts
+import { TRPCError } from '@trpc/server';
+import { publicProcedure } from './trpc';
+
+const proc = publicProcedure.query(() => {
+  throw new TRPCError({
+    code: 'NOT_FOUND',
+    message: 'User not found',
+  });
+  // client receives 404 NOT_FOUND
+});
+```
+
+Plain Error objects are caught and wrapped as INTERNAL_SERVER_ERROR (500); use TRPCError with a specific code for proper HTTP status mapping.
+
+Source: www/docs/server/error-handling.md
+
+### [MEDIUM] Expecting stack traces in production
+
+Wrong:
+
+```ts
+import { initTRPC } from '@trpc/server';
+
+// No explicit isDev setting
+const t = initTRPC.create();
+// Stack traces may or may not appear depending on NODE_ENV
+```
+
+Correct:
+
+```ts
+import { initTRPC } from '@trpc/server';
+
+const t = initTRPC.create({
+  isDev: process.env.NODE_ENV === 'development',
+});
+```
+
+Stack traces are included only when `isDev` is true (default: `NODE_ENV !== "production"`); set `isDev` explicitly for deterministic behavior across runtimes.
+
+Source: www/docs/server/error-handling.md
+
+### [HIGH] Not handling Zod errors in errorFormatter
+
+Wrong:
+
+```ts
+import { initTRPC } from '@trpc/server';
+
+// No errorFormatter -- client gets generic "Input validation failed"
+const t = initTRPC.create();
+```
+
+Correct:
+
+```ts
+import { initTRPC } from '@trpc/server';
+import { ZodError } from 'zod';
+
+const t = initTRPC.create({
+  errorFormatter({ shape, error }) {
+    return {
+      ...shape,
+      data: {
+        ...shape.data,
+        zodError:
+          error.code === 'BAD_REQUEST' && error.cause instanceof ZodError
+            ? error.cause.flatten()
+            : null,
+      },
+    };
+  },
+});
+```
+
+Without a custom errorFormatter, the client receives a generic message without field-level validation details from Zod.
+
+Source: www/docs/server/error-formatting.md
+
+## Error Code Reference
+
+| Code                  | HTTP | Use when                             |
+| --------------------- | ---- | ------------------------------------ |
+| BAD_REQUEST           | 400  | Invalid input                        |
+| UNAUTHORIZED          | 401  | Missing or invalid auth credentials  |
+| FORBIDDEN             | 403  | Authenticated but not authorized     |
+| NOT_FOUND             | 404  | Resource does not exist              |
+| CONFLICT              | 409  | Request conflicts with current state |
+| UNPROCESSABLE_CONTENT | 422  | Valid syntax but semantic error      |
+| TOO_MANY_REQUESTS     | 429  | Rate limit exceeded                  |
+| INTERNAL_SERVER_ERROR | 500  | Unexpected server error              |
+
+## See Also
+
+- `server-setup` -- initTRPC configuration including isDev
+- `validators` -- input validation that triggers BAD_REQUEST errors
+- `middlewares` -- auth middleware throwing UNAUTHORIZED
+- `server-side-calls` -- catching TRPCError in server-side callers

package/skills/middlewares/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: middlewares
+description: >
+  Create and compose tRPC middleware with t.procedure.use(), extend context via
+  opts.next({ ctx }), build reusable middleware with .concat() and .unstable_pipe(),
+  define base procedures like publicProcedure and authedProcedure. Access raw input
+  with getRawInput(). Logging, timing, OTEL tracing patterns.
+type: core
+library: trpc
+library_version: '11.14.0'
+requires:
+  - server-setup
+sources:
+  - 'trpc/trpc:www/docs/server/middlewares.md'
+  - 'trpc/trpc:www/docs/server/authorization.md'
+  - 'trpc/trpc:packages/server/src/unstable-core-do-not-import/middleware.ts'
+  - 'trpc/trpc:packages/server/src/unstable-core-do-not-import/procedureBuilder.ts'
+---
+
+# tRPC -- Middlewares
+
+## Setup
+
+```ts
+// server/trpc.ts
+import { initTRPC, TRPCError } from '@trpc/server';
+
+type Context = {
+  user?: { id: string; isAdmin: boolean };
+};
+
+const t = initTRPC.context<Context>().create();
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+export const middleware = t.middleware;
+```
+
+## Core Patterns
+
+### Auth middleware that narrows context type
+
+```ts
+// server/trpc.ts
+import { initTRPC, TRPCError } from '@trpc/server';
+
+type Context = {
+  user?: { id: string; isAdmin: boolean };
+};
+
+const t = initTRPC.context<Context>().create();
+
+export const publicProcedure = t.procedure;
+
+export const authedProcedure = t.procedure.use(async (opts) => {
+  const { ctx } = opts;
+  if (!ctx.user) {
+    throw new TRPCError({ code: 'UNAUTHORIZED' });
+  }
+  return opts.next({
+    ctx: {
+      user: ctx.user,
+    },
+  });
+});
+
+export const adminProcedure = t.procedure.use(async (opts) => {
+  const { ctx } = opts;
+  if (!ctx.user?.isAdmin) {
+    throw new TRPCError({ code: 'UNAUTHORIZED' });
+  }
+  return opts.next({
+    ctx: {
+      user: ctx.user,
+    },
+  });
+});
+```
+
+After the middleware, `ctx.user` is non-nullable in downstream procedures.
+
+### Logging and timing middleware
+
+```ts
+// server/trpc.ts
+import { initTRPC } from '@trpc/server';
+
+const t = initTRPC.create();
+
+export const loggedProcedure = t.procedure.use(async (opts) => {
+  const start = Date.now();
+
+  const result = await opts.next();
+
+  const durationMs = Date.now() - start;
+  const meta = { path: opts.path, type: opts.type, durationMs };
+
+  result.ok
+    ? console.log('OK request timing:', meta)
+    : console.error('Non-OK request timing', meta);
+
+  return result;
+});
+```
+
+### Reusable middleware with .concat()
+
+```ts
+// myPlugin.ts
+import { initTRPC } from '@trpc/server';
+
+export function createMyPlugin() {
+  const t = initTRPC.context<{}>().meta<{}>().create();
+
+  return {
+    pluginProc: t.procedure.use((opts) => {
+      return opts.next({
+        ctx: {
+          fromPlugin: 'hello from myPlugin' as const,
+        },
+      });
+    }),
+  };
+}
+```
+
+```ts
+// server/trpc.ts
+import { initTRPC } from '@trpc/server';
+import { createMyPlugin } from './myPlugin';
+
+const t = initTRPC.context<{}>().create();
+const plugin = createMyPlugin();
+
+export const publicProcedure = t.procedure;
+
+export const procedureWithPlugin = publicProcedure.concat(plugin.pluginProc);
+```
+
+`.concat()` merges a partial procedure (from any tRPC instance) into your procedure chain, as long as context and meta types overlap.
+
+### Extending middlewares with .unstable_pipe()
+
+```ts
+import { initTRPC } from '@trpc/server';
+
+const t = initTRPC.create();
+
+const fooMiddleware = t.middleware((opts) => {
+  return opts.next({
+    ctx: { foo: 'foo' as const },
+  });
+});
+
+const barMiddleware = fooMiddleware.unstable_pipe((opts) => {
+  console.log(opts.ctx.foo);
+  return opts.next({
+    ctx: { bar: 'bar' as const },
+  });
+});
+
+const barProcedure = t.procedure.use(barMiddleware);
+```
+
+Piped middlewares run in order and each receives the context from the previous middleware.
+
+## Common Mistakes
+
+### [CRITICAL] Forgetting to call and return opts.next()
+
+Wrong:
+
+```ts
+import { initTRPC } from '@trpc/server';
+
+const t = initTRPC.create();
+
+const logMiddleware = t.middleware(async (opts) => {
+  console.log('request started');
+  // forgot to call opts.next()
+});
+```
+
+Correct:
+
+```ts
+import { initTRPC } from '@trpc/server';
+
+const t = initTRPC.create();
+
+const logMiddleware = t.middleware(async (opts) => {
+  console.log('request started');
+  const result = await opts.next();
+  console.log('request ended');
+  return result;
+});
+```
+
+Middleware must call `opts.next()` and return its result; forgetting this silently drops the request with an INTERNAL_SERVER_ERROR because no middleware marker is returned.
+
+Source: packages/server/src/unstable-core-do-not-import/procedureBuilder.ts
+
+### [HIGH] Extending context with wrong type in opts.next()
+
+Wrong:
+
+```ts
+import { initTRPC } from '@trpc/server';
+
+const t = initTRPC.create();
+
+const middleware = t.middleware(async (opts) => {
+  return opts.next({ ctx: 'not-an-object' });
+});
+```
+
+Correct:
+
+```ts
+import { initTRPC } from '@trpc/server';
+
+const t = initTRPC.create();
+
+async function getUser() {
+  return { id: '1', name: 'Katt' };
+}
+
+const middleware = t.middleware(async (opts) => {
+  return opts.next({ ctx: { user: await getUser() } });
+});
+```
+
+Context extension in `opts.next({ ctx })` must be an object; passing non-object values or overwriting required keys breaks downstream procedures.
+
+Source: www/docs/server/middlewares.md
+
+## See Also
+
+- `server-setup` -- initTRPC, routers, procedures, context
+- `validators` -- input/output validation with Zod
+- `error-handling` -- TRPCError codes used in auth middleware
+- `auth` -- full auth patterns combining middleware + client headers