@trpc/server 11.14.0 → 11.14.1

package/package.json

@@ -2,7 +2,7 @@
   "name": "@trpc/server",
   "type": "module",
   "sideEffects": false,
-  "version": "11.14.0",
+  "version": "11.14.1",
   "description": "The tRPC server library",
   "author": "KATT",
   "license": "MIT",
@@ -187,7 +187,10 @@
     "shared",
     "unstable-core-do-not-import",
     "!**/*.test.*",
-    "!**/__tests__"
+    "!**/__tests__",
+    "skills",
+    "!skills/_artifacts",
+    "bin"
   ],
   "publishConfig": {
     "access": "public"
@@ -195,6 +198,7 @@
   "devDependencies": {
     "@fastify/websocket": "^11.0.0",
     "@oxc-project/runtime": "0.115.0",
+    "@tanstack/intent": "^0.0.20",
     "@tanstack/react-query": "^5.80.3",
     "@types/aws-lambda": "^8.10.149",
     "@types/express": "^5.0.0",
@@ -228,5 +232,11 @@
   "peerDependencies": {
     "typescript": ">=5.7.2"
   },
-  "gitHead": "6e03f5c2f8d8ebaa237747d2db447737393402c6"
+  "keywords": [
+    "tanstack-intent"
+  ],
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
+  "gitHead": "e896259af491fc4b1c9e8fc320817e2222bae869"
 }

package/skills/adapter-aws-lambda/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: adapter-aws-lambda
+description: >
+  Deploy tRPC on AWS Lambda with awsLambdaRequestHandler() from
+  @trpc/server/adapters/aws-lambda for API Gateway v1 (REST, APIGatewayProxyEvent)
+  and v2 (HTTP, APIGatewayProxyEventV2), and Lambda Function URLs. Enable response
+  streaming with awsLambdaStreamingRequestHandler() wrapped in
+  awslambda.streamifyResponse(). CreateAWSLambdaContextOptions provides event and
+  context for context creation.
+type: core
+library: trpc
+library_version: '11.14.0'
+requires:
+  - server-setup
+sources:
+  - www/docs/server/adapters/aws-lambda.md
+  - examples/lambda-url/
+  - examples/lambda-api-gateway/
+---
+
+# tRPC — Adapter: AWS Lambda
+
+## Setup
+
+```ts
+// server.ts
+import { initTRPC } from '@trpc/server';
+import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
+import { awsLambdaRequestHandler } from '@trpc/server/adapters/aws-lambda';
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { z } from 'zod';
+
+const t = initTRPC.create();
+
+const appRouter = t.router({
+  greet: t.procedure
+    .input(z.object({ name: z.string() }))
+    .query(({ input }) => ({ greeting: `Hello, ${input.name}!` })),
+});
+
+export type AppRouter = typeof appRouter;
+
+const createContext = ({
+  event,
+  context,
+}: CreateAWSLambdaContextOptions<APIGatewayProxyEventV2>) => ({
+  event,
+  lambdaContext: context,
+});
+
+export const handler = awsLambdaRequestHandler({
+  router: appRouter,
+  createContext,
+});
+```
+
+## Core Patterns
+
+### API Gateway v1 (REST) handler
+
+```ts
+import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
+import { awsLambdaRequestHandler } from '@trpc/server/adapters/aws-lambda';
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+import { appRouter } from './router';
+
+const createContext = ({
+  event,
+  context,
+}: CreateAWSLambdaContextOptions<APIGatewayProxyEvent>) => ({
+  user: event.requestContext.authorizer?.claims,
+});
+
+export const handler = awsLambdaRequestHandler({
+  router: appRouter,
+  createContext,
+});
+```
+
+Use `APIGatewayProxyEvent` for REST API (v1 payload format) and `APIGatewayProxyEventV2` for HTTP API (v2 payload format).
+
+### Response streaming with awsLambdaStreamingRequestHandler
+
+```ts
+/// <reference types="aws-lambda" />
+import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
+import { awsLambdaStreamingRequestHandler } from '@trpc/server/adapters/aws-lambda';
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { appRouter } from './router';
+
+const createContext = ({
+  event,
+  context,
+}: CreateAWSLambdaContextOptions<APIGatewayProxyEventV2>) => ({});
+
+export const handler = awslambda.streamifyResponse(
+  awsLambdaStreamingRequestHandler({
+    router: appRouter,
+    createContext,
+  }),
+);
+```
+
+Response streaming is supported for Lambda Function URLs and API Gateway REST APIs (with `responseTransferMode: STREAM`). The `awslambda` namespace is provided by the Lambda execution environment.
+
+### Streaming async generator procedure
+
+```ts
+import { initTRPC } from '@trpc/server';
+
+const t = initTRPC.create();
+
+export const appRouter = t.router({
+  countdown: t.procedure.query(async function* () {
+    for (let i = 10; i >= 0; i--) {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      yield i;
+    }
+  }),
+});
+```
+
+Pair with `httpBatchStreamLink` on the client for streamed responses.
+
+## Common Mistakes
+
+### HIGH Using httpBatchLink with per-procedure API Gateway resources
+
+Wrong:
+
+```ts
+// API Gateway has a separate resource for each procedure
+// e.g., /getUser, /createUser
+// Client uses:
+import { httpBatchLink } from '@trpc/client';
+
+httpBatchLink({ url: 'https://api.example.com' });
+// Batch request to /getUser,createUser → 404
+```
+
+Correct:
+
+```ts
+import { httpBatchLink, httpLink } from '@trpc/client';
+
+// Option A: Single catch-all resource (e.g., /{proxy+})
+httpBatchLink({ url: 'https://api.example.com' });
+
+// Option B: Per-procedure resources with httpLink (no batching)
+httpLink({ url: 'https://api.example.com' });
+```
+
+`httpBatchLink` sends multiple procedure names in the URL path (e.g., `getUser,createUser`). If API Gateway routes are per-procedure, the combined path does not match any resource and returns 404. Use a single catch-all resource or switch to `httpLink`.
+
+Source: www/docs/server/adapters/aws-lambda.md
+
+### HIGH Forgetting streamifyResponse wrapper for streaming
+
+Wrong:
+
+```ts
+export const handler = awsLambdaStreamingRequestHandler({
+  router: appRouter,
+  createContext,
+});
+```
+
+Correct:
+
+```ts
+export const handler = awslambda.streamifyResponse(
+  awsLambdaStreamingRequestHandler({
+    router: appRouter,
+    createContext,
+  }),
+);
+```
+
+`awsLambdaStreamingRequestHandler` requires wrapping with `awslambda.streamifyResponse()` to enable Lambda response streaming. Without it, Lambda treats the handler as a standard buffered response.
+
+Source: www/docs/server/adapters/aws-lambda.md
+
+## See Also
+
+- **server-setup** -- `initTRPC.create()`, router/procedure definition, context
+- **adapter-fetch** -- alternative for edge/serverless runtimes using Fetch API
+- **links** -- `httpBatchLink` vs `httpLink` for API Gateway routing considerations
+- AWS Lambda docs: https://docs.aws.amazon.com/lambda/latest/dg/welcome.html

package/skills/adapter-express/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: adapter-express
+description: >
+  Mount tRPC as Express middleware with createExpressMiddleware() from
+  @trpc/server/adapters/express. Access Express req/res in createContext via
+  CreateExpressContextOptions. Mount at a path prefix like app.use('/trpc', ...).
+  Avoid global express.json() conflicting with tRPC body parsing for FormData.
+type: core
+library: trpc
+library_version: '11.14.0'
+requires:
+  - server-setup
+sources:
+  - www/docs/server/adapters/express.md
+  - examples/express-server/src/server.ts
+---
+
+# tRPC — Adapter: Express
+
+## Setup
+
+```ts
+// server.ts
+import { initTRPC } from '@trpc/server';
+import * as trpcExpress from '@trpc/server/adapters/express';
+import express from 'express';
+import { z } from 'zod';
+
+const createContext = ({
+  req,
+  res,
+}: trpcExpress.CreateExpressContextOptions) => {
+  return { req, res };
+};
+type Context = Awaited<ReturnType<typeof createContext>>;
+
+const t = initTRPC.context<Context>().create();
+
+const appRouter = t.router({
+  greet: t.procedure
+    .input(z.object({ name: z.string() }))
+    .query(({ input }) => ({ greeting: `Hello, ${input.name}!` })),
+});
+
+export type AppRouter = typeof appRouter;
+
+const app = express();
+
+app.use(
+  '/trpc',
+  trpcExpress.createExpressMiddleware({
+    router: appRouter,
+    createContext,
+  }),
+);
+
+app.listen(4000, () => {
+  console.log('Listening on http://localhost:4000');
+});
+```
+
+## Core Patterns
+
+### Accessing Express req/res in context
+
+```ts
+import * as trpcExpress from '@trpc/server/adapters/express';
+
+const createContext = ({
+  req,
+  res,
+}: trpcExpress.CreateExpressContextOptions) => {
+  const token = req.headers.authorization?.split(' ')[1];
+  return { token, res };
+};
+
+type Context = Awaited<ReturnType<typeof createContext>>;
+```
+
+`CreateExpressContextOptions` provides typed access to the Express `req` (IncomingMessage) and `res` (ServerResponse).
+
+### Adding tRPC alongside existing Express routes
+
+```ts
+import * as trpcExpress from '@trpc/server/adapters/express';
+import cors from 'cors';
+import express from 'express';
+import { createContext } from './context';
+import { appRouter } from './router';
+
+const app = express();
+
+app.use(cors());
+
+app.get('/health', (_req, res) => {
+  res.json({ status: 'ok' });
+});
+
+app.use(
+  '/trpc',
+  trpcExpress.createExpressMiddleware({
+    router: appRouter,
+    createContext,
+  }),
+);
+
+app.listen(4000);
+```
+
+## Common Mistakes
+
+### HIGH Global express.json() consuming tRPC request body
+
+Wrong:
+
+```ts
+const app = express();
+app.use(express.json()); // global body parser
+app.use(
+  '/trpc',
+  trpcExpress.createExpressMiddleware({
+    router: appRouter,
+    createContext,
+  }),
+);
+```
+
+Correct:
+
+```ts
+const app = express();
+// Only apply body parser to non-tRPC routes
+app.use('/api', express.json());
+app.use(
+  '/trpc',
+  trpcExpress.createExpressMiddleware({
+    router: appRouter,
+    createContext,
+  }),
+);
+```
+
+If `express.json()` is applied globally before the tRPC middleware, it consumes and parses the request body. tRPC then receives an already-parsed body, which breaks FormData and binary content type handling.
+
+Source: www/docs/server/non-json-content-types.md
+
+## See Also
+
+- **server-setup** -- `initTRPC.create()`, router/procedure definition, context
+- **adapter-standalone** -- simpler adapter when Express middleware ecosystem is not needed
+- **auth** -- extracting JWT from `req.headers.authorization` in context
+- Express docs: https://expressjs.com/en/guide/using-middleware.html

package/skills/adapter-fastify/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: adapter-fastify
+description: >
+  Mount tRPC as a Fastify plugin with fastifyTRPCPlugin from
+  @trpc/server/adapters/fastify. Configure prefix, trpcOptions (router,
+  createContext, onError). Enable WebSocket subscriptions with useWSS and
+  @fastify/websocket. Set routerOptions.maxParamLength for batch requests.
+  Requires Fastify v5+. FastifyTRPCPluginOptions for type-safe onError.
+  CreateFastifyContextOptions provides req, res.
+type: core
+library: trpc
+library_version: '11.14.0'
+requires:
+  - server-setup
+sources:
+  - www/docs/server/adapters/fastify.md
+  - examples/fastify-server/
+---
+
+# tRPC — Adapter: Fastify
+
+## Setup
+
+```ts
+// server.ts
+import { initTRPC } from '@trpc/server';
+import {
+  fastifyTRPCPlugin,
+  FastifyTRPCPluginOptions,
+} from '@trpc/server/adapters/fastify';
+import type { CreateFastifyContextOptions } from '@trpc/server/adapters/fastify';
+import fastify from 'fastify';
+import { z } from 'zod';
+
+function createContext({ req, res }: CreateFastifyContextOptions) {
+  return { req, res };
+}
+type Context = Awaited<ReturnType<typeof createContext>>;
+
+const t = initTRPC.context<Context>().create();
+
+const appRouter = t.router({
+  greet: t.procedure
+    .input(z.object({ name: z.string() }))
+    .query(({ input }) => ({ greeting: `Hello, ${input.name}!` })),
+});
+
+export type AppRouter = typeof appRouter;
+
+const server = fastify({
+  routerOptions: {
+    maxParamLength: 5000,
+  },
+});
+
+server.register(fastifyTRPCPlugin, {
+  prefix: '/trpc',
+  trpcOptions: {
+    router: appRouter,
+    createContext,
+    onError({ path, error }) {
+      console.error(`Error in tRPC handler on path '${path}':`, error);
+    },
+  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
+});
+
+(async () => {
+  try {
+    await server.listen({ port: 3000 });
+    console.log('Listening on http://localhost:3000');
+  } catch (err) {
+    server.log.error(err);
+    process.exit(1);
+  }
+})();
+```
+
+## Core Patterns
+
+### WebSocket subscriptions with @fastify/websocket
+
+```ts
+import ws from '@fastify/websocket';
+import {
+  fastifyTRPCPlugin,
+  FastifyTRPCPluginOptions,
+} from '@trpc/server/adapters/fastify';
+import fastify from 'fastify';
+import { createContext } from './context';
+import { appRouter, type AppRouter } from './router';
+
+const server = fastify({
+  routerOptions: { maxParamLength: 5000 },
+});
+
+// Register @fastify/websocket BEFORE the tRPC plugin
+server.register(ws);
+
+server.register(fastifyTRPCPlugin, {
+  prefix: '/trpc',
+  useWSS: true,
+  trpcOptions: {
+    router: appRouter,
+    createContext,
+    keepAlive: {
+      enabled: true,
+      pingMs: 30000,
+      pongWaitMs: 5000,
+    },
+  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
+});
+
+server.listen({ port: 3000 });
+```
+
+Install: `npm install @fastify/websocket` (minimum version 3.11.0)
+
+### Type-safe onError with satisfies
+
+```ts
+server.register(fastifyTRPCPlugin, {
+  prefix: '/trpc',
+  trpcOptions: {
+    router: appRouter,
+    createContext,
+    onError({ path, error, type, input }) {
+      console.error(`[${type}] ${path}:`, error.message);
+    },
+  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
+});
+```
+
+Due to Fastify plugin type inference limitations, use `satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions']` to get correct types on `onError` and other callbacks.
+
+## Common Mistakes
+
+### HIGH Registering @fastify/websocket after tRPC plugin
+
+Wrong:
+
+```ts
+server.register(fastifyTRPCPlugin, {
+  useWSS: true,
+  trpcOptions: { router: appRouter, createContext },
+});
+server.register(ws); // too late!
+```
+
+Correct:
+
+```ts
+server.register(ws); // register FIRST
+server.register(fastifyTRPCPlugin, {
+  useWSS: true,
+  trpcOptions: { router: appRouter, createContext },
+});
+```
+
+The WebSocket plugin must be registered before the tRPC plugin. Reverse order causes WebSocket routes to not be recognized.
+
+Source: www/docs/server/adapters/fastify.md
+
+### HIGH Missing maxParamLength for batch requests
+
+Wrong:
+
+```ts
+const server = fastify();
+```
+
+Correct:
+
+```ts
+const server = fastify({
+  routerOptions: { maxParamLength: 5000 },
+});
+```
+
+Fastify defaults to `maxParamLength: 100`. Batch requests from `httpBatchLink` encode multiple procedure names in the URL path parameter, which easily exceeds 100 characters and returns a 404.
+
+Source: www/docs/server/adapters/fastify.md
+
+### CRITICAL Using Fastify v4 with tRPC v11
+
+Wrong:
+
+```json
+{ "dependencies": { "fastify": "^4.0.0" } }
+```
+
+Correct:
+
+```json
+{ "dependencies": { "fastify": "^5.0.0" } }
+```
+
+tRPC v11 requires Fastify v5+. Fastify v4 may return empty responses without errors due to incompatible response handling.
+
+Source: www/docs/server/adapters/fastify.md
+
+## See Also
+
+- **server-setup** -- `initTRPC.create()`, router/procedure definition, context
+- **subscriptions** -- async generator subscriptions, `tracked()`, `keepAlive`
+- **adapter-standalone** -- simpler adapter when Fastify features are not needed
+- Fastify docs: https://fastify.dev/docs/latest/