@trpc/server 11.14.0 → 11.14.1

package/skills/non-json-content-types/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: non-json-content-types
+description: >
+  Handle FormData, file uploads, Blob, Uint8Array, and ReadableStream inputs in
+  tRPC mutations. Use octetInputParser from @trpc/server/http for binary data.
+  Route non-JSON requests with splitLink and isNonJsonSerializable() from
+  @trpc/client. FormData and binary inputs only work with mutations (POST).
+type: core
+library: trpc
+library_version: '11.14.0'
+requires:
+  - server-setup
+  - links
+sources:
+  - 'trpc/trpc:www/docs/server/non-json-content-types.md'
+  - 'trpc/trpc:examples/next-formdata/'
+---
+
+# tRPC -- Non-JSON Content Types
+
+## Setup
+
+Server:
+
+```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 { octetInputParser } from '@trpc/server/http';
+import { z } from 'zod';
+import { publicProcedure, router } from './trpc';
+
+export const appRouter = router({
+  uploadForm: publicProcedure
+    .input(z.instanceof(FormData))
+    .mutation(({ input }) => {
+      const name = input.get('name');
+      return { greeting: `Hello ${name}` };
+    }),
+  uploadFile: publicProcedure.input(octetInputParser).mutation(({ input }) => {
+    // input is a ReadableStream
+    return { valid: true };
+  }),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+Client:
+
+```ts
+// client/index.ts
+import {
+  createTRPCClient,
+  httpBatchLink,
+  httpLink,
+  isNonJsonSerializable,
+  splitLink,
+} from '@trpc/client';
+import type { AppRouter } from '../server/appRouter';
+
+const url = 'http://localhost:3000';
+
+const trpc = createTRPCClient<AppRouter>({
+  links: [
+    splitLink({
+      condition: (op) => isNonJsonSerializable(op.input),
+      true: httpLink({ url }),
+      false: httpBatchLink({ url }),
+    }),
+  ],
+});
+```
+
+## Core Patterns
+
+### FormData mutation
+
+```ts
+// server/appRouter.ts
+import { z } from 'zod';
+import { publicProcedure, router } from './trpc';
+
+export const appRouter = router({
+  createPost: publicProcedure
+    .input(z.instanceof(FormData))
+    .mutation(({ input }) => {
+      const title = input.get('title') as string;
+      const body = input.get('body') as string;
+      return { id: '1', title, body };
+    }),
+});
+```
+
+```ts
+// client usage
+const form = new FormData();
+form.append('title', 'Hello');
+form.append('body', 'World');
+
+const result = await trpc.createPost.mutate(form);
+```
+
+### Binary file upload with octetInputParser
+
+```ts
+// server/appRouter.ts
+import { octetInputParser } from '@trpc/server/http';
+import { publicProcedure, router } from './trpc';
+
+export const appRouter = router({
+  upload: publicProcedure
+    .input(octetInputParser)
+    .mutation(async ({ input }) => {
+      const reader = input.getReader();
+      let totalBytes = 0;
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        totalBytes += value.byteLength;
+      }
+      return { totalBytes };
+    }),
+});
+```
+
+```ts
+// client usage
+const file = new File(['hello world'], 'test.txt', { type: 'text/plain' });
+const result = await trpc.upload.mutate(file);
+```
+
+`octetInputParser` converts Blob, Uint8Array, and File inputs to a ReadableStream on the server.
+
+### Client splitLink with superjson transformer
+
+```ts
+import {
+  createTRPCClient,
+  httpBatchLink,
+  httpLink,
+  isNonJsonSerializable,
+  splitLink,
+} from '@trpc/client';
+import superjson from 'superjson';
+import type { AppRouter } from '../server/appRouter';
+
+const url = 'http://localhost:3000';
+
+const trpc = createTRPCClient<AppRouter>({
+  links: [
+    splitLink({
+      condition: (op) => isNonJsonSerializable(op.input),
+      true: httpLink({
+        url,
+        transformer: {
+          serialize: (data) => data,
+          deserialize: (data) => superjson.deserialize(data),
+        },
+      }),
+      false: httpBatchLink({
+        url,
+        transformer: superjson,
+      }),
+    }),
+  ],
+});
+```
+
+When using a transformer, the non-JSON httpLink needs a custom transformer that skips serialization for the request (FormData/binary cannot be transformed) but deserializes the response.
+
+## Common Mistakes
+
+### [HIGH] Using httpBatchLink for FormData requests
+
+Wrong:
+
+```ts
+import { createTRPCClient, httpBatchLink } from '@trpc/client';
+import type { AppRouter } from '../server/appRouter';
+
+const trpc = createTRPCClient<AppRouter>({
+  links: [httpBatchLink({ url: 'http://localhost:3000' })],
+});
+```
+
+Correct:
+
+```ts
+import {
+  createTRPCClient,
+  httpBatchLink,
+  httpLink,
+  isNonJsonSerializable,
+  splitLink,
+} from '@trpc/client';
+import type { AppRouter } from '../server/appRouter';
+
+const url = 'http://localhost:3000';
+
+const trpc = createTRPCClient<AppRouter>({
+  links: [
+    splitLink({
+      condition: (op) => isNonJsonSerializable(op.input),
+      true: httpLink({ url }),
+      false: httpBatchLink({ url }),
+    }),
+  ],
+});
+```
+
+FormData and binary inputs are not batchable; use `splitLink` with `isNonJsonSerializable()` to route them through `httpLink`.
+
+Source: www/docs/server/non-json-content-types.md
+
+### [HIGH] Global body parser intercepting FormData before tRPC
+
+Wrong:
+
+```ts
+import * as trpcExpress from '@trpc/server/adapters/express';
+import express from 'express';
+import { appRouter } from './appRouter';
+
+const app = express();
+app.use(express.json());
+app.use('/trpc', trpcExpress.createExpressMiddleware({ router: appRouter }));
+```
+
+Correct:
+
+```ts
+import * as trpcExpress from '@trpc/server/adapters/express';
+import express from 'express';
+import { appRouter } from './appRouter';
+
+const app = express();
+app.use('/api', express.json());
+app.use('/trpc', trpcExpress.createExpressMiddleware({ router: appRouter }));
+```
+
+A global `express.json()` middleware consumes the request body before tRPC can read it; scope body parsing to non-tRPC routes only.
+
+Source: www/docs/server/non-json-content-types.md
+
+### [HIGH] FormData only works with mutations
+
+FormData and binary inputs are only supported for mutations (POST requests). Using them with `.query()` throws an error because queries use HTTP GET which cannot carry a request body.
+
+Source: www/docs/server/non-json-content-types.md
+
+## See Also
+
+- `server-setup` -- initTRPC, routers, procedures
+- `links` -- splitLink configuration for routing non-JSON requests
+- `validators` -- z.instanceof(FormData) for FormData validation
+- `adapter-express` -- Express-specific body parser considerations

package/skills/server-setup/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: server-setup
+description: >
+  Initialize tRPC with initTRPC.create(), define routers with t.router(),
+  create procedures with .query()/.mutation()/.subscription(), configure context
+  with createContext(), export AppRouter type, merge routers with t.mergeRouters(),
+  lazy-load routers with lazy().
+type: core
+library: trpc
+library_version: '11.14.0'
+requires: []
+sources:
+  - 'trpc/trpc:www/docs/server/overview.md'
+  - 'trpc/trpc:www/docs/server/routers.md'
+  - 'trpc/trpc:www/docs/server/procedures.md'
+  - 'trpc/trpc:www/docs/server/context.md'
+  - 'trpc/trpc:www/docs/server/merging-routers.md'
+  - 'trpc/trpc:www/docs/main/quickstart.mdx'
+  - 'trpc/trpc:packages/server/src/unstable-core-do-not-import/initTRPC.ts'
+  - 'trpc/trpc:packages/server/src/unstable-core-do-not-import/router.ts'
+---
+
+# 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