# adapter-aws-lambda

Shows how to run a tRPC API on AWS Lambda behind API Gateway or Function URLs, including response streaming.

Skill by tRPC. Category: Shipping and ops.

## Install

Project (for this project only):

```sh
npx skills add trpc/trpc --skill adapter-aws-lambda
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add trpc/trpc --skill adapter-aws-lambda -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 42. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/site/trpc.trpc/adapter-aws-lambda)

## Source

[Open the source](https://github.com/trpc/trpc/tree/HEAD/packages/server/skills/adapter-aws-lambda). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
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.16.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.

### Limiting batch size with maxBatchSize

```ts
import { awsLambdaRequestHandler } from '@trpc/server/adapters/aws-lambda';
import { appRouter } from './router';

export const handler = awsLambdaRequestHandler({
  router: appRouter,
  createContext,
  maxBatchSize: 10,
});
```

Requests batching more than `maxBatchSize` operations are rejected with a `400 Bad Request` error. Set `maxItems` on your client's `httpBatchLink` to the same value to avoid exceeding the limit.

## 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
````

- Previous: [adapter-express](https://syn4pse.dev/terminal/trpc-adapter-express.md)
- Next: [chakra-ui-builder](https://syn4pse.dev/terminal/chakra-ui-builder.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
