> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/honojs/hono/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Lambda

> API reference for the AWS Lambda adapter

The AWS Lambda adapter converts Hono applications into AWS Lambda handlers that work with API Gateway, ALB, Lambda Function URLs, and VPC Lattice.

## Import

```ts theme={null}
import { 
  handle, 
  streamHandle, 
  defaultIsContentTypeBinary, 
  getConnInfo 
} from 'hono/aws-lambda'
import type { 
  LambdaEvent, 
  APIGatewayProxyResult,
  ApiGatewayRequestContext,
  ApiGatewayRequestContextV2,
  ALBRequestContext,
  LambdaContext
} from 'hono/aws-lambda'
```

## Functions

### handle()

Converts a Hono application to an AWS Lambda handler.

Accepts events from API Gateway (v1 and v2), Application Load Balancer (ALB), Lambda Function URLs, and VPC Lattice.

```ts theme={null}
function handle<E extends Env, S extends Schema, BasePath extends string>(
  app: Hono<E, S, BasePath>,
  options?: HandleOptions
): LambdaHandler
```

#### Parameters

* `app` - The Hono application instance
* `options` - Optional configuration:
  * `isContentTypeBinary` - `(contentType: string) => boolean` - Function to determine if content should be base64 encoded

#### Returns

Lambda handler function compatible with API Gateway, ALB, and Function URLs.

#### Example

```ts theme={null}
import { Hono } from 'hono'
import { handle } from 'hono/aws-lambda'

const app = new Hono()

app.get('/', (c) => c.text('Hello from Lambda!'))
app.post('/api/users', async (c) => {
  const body = await c.req.json()
  return c.json({ success: true, data: body })
})

app.get('/image', (c) => {
  // Binary responses are automatically base64 encoded
  return c.body(imageBuffer, 200, {
    'Content-Type': 'image/png'
  })
})

export const handler = handle(app)
```

#### Custom Binary Content Detection

```ts theme={null}
import { handle, defaultIsContentTypeBinary } from 'hono/aws-lambda'

export const handler = handle(app, {
  isContentTypeBinary: (contentType) => {
    // Use default logic
    if (defaultIsContentTypeBinary(contentType)) {
      return true
    }
    // Add custom binary types
    return contentType.startsWith('image/') || 
           contentType === 'application/pdf' ||
           contentType === 'application/zip'
  }
})
```

### streamHandle()

Creates a streaming Lambda handler that uses response streaming for better performance with large responses.

```ts theme={null}
function streamHandle<E extends Env, S extends Schema, BasePath extends string>(
  app: Hono<E, S, BasePath>
): StreamingLambdaHandler
```

<Note>
  Streaming responses require Lambda function URLs or API Gateway HTTP APIs configured for streaming. This feature requires the AWS Lambda runtime to support response streaming.
</Note>

#### Example

```ts theme={null}
import { Hono } from 'hono'
import { streamHandle } from 'hono/aws-lambda'

const app = new Hono()

app.get('/large-data', async (c) => {
  // Stream large responses efficiently
  const stream = new ReadableStream({
    start(controller) {
      for (let i = 0; i < 10000; i++) {
        controller.enqueue(`Line ${i}\n`)
      }
      controller.close()
    }
  })
  return c.body(stream)
})

export const handler = streamHandle(app)
```

### defaultIsContentTypeBinary()

Default function to determine if a content type should be base64 encoded.

```ts theme={null}
function defaultIsContentTypeBinary(contentType: string): boolean
```

#### Returns

`true` if the content type is binary, `false` otherwise.

#### Logic

Returns `false` for:

* `text/*` (text/plain, text/html, text/css, text/javascript, text/csv)
* Content types containing `json` or `xml` (including `application/json`, `application/xml`, `+json`, `+xml`)

Returns `true` for all other content types.

### getConnInfo()

Extracts connection information from AWS Lambda events.

```ts theme={null}
function getConnInfo(c: Context): ConnInfo
```

Works with multiple event sources:

* API Gateway v1 (REST API): `requestContext.identity.sourceIp`
* API Gateway v2 (HTTP API/Function URLs): `requestContext.http.sourceIp`
* ALB: Falls back to `x-forwarded-for` header

#### Returns

```ts theme={null}
interface ConnInfo {
  remote: {
    address?: string  // Client IP address
  }
}
```

#### Example

```ts theme={null}
import { Hono } from 'hono'
import { handle, getConnInfo } from 'hono/aws-lambda'

const app = new Hono()

app.get('/', (c) => {
  const info = getConnInfo(c)
  return c.text(`Your IP: ${info.remote.address}`)
})

app.get('/request-info', (c) => {
  const info = getConnInfo(c)
  const requestContext = c.env.requestContext
  
  return c.json({
    ip: info.remote.address,
    requestId: requestContext.requestId,
    stage: 'stage' in requestContext ? requestContext.stage : undefined
  })
})

export const handler = handle(app)
```

## Types

### LambdaEvent

Union type of all supported Lambda event types:

```ts theme={null}
type LambdaEvent = 
  | APIGatewayProxyEvent      // API Gateway REST API (v1)
  | APIGatewayProxyEventV2    // API Gateway HTTP API (v2) / Function URLs
  | ALBProxyEvent             // Application Load Balancer
  | LatticeProxyEventV2       // VPC Lattice
```

### APIGatewayProxyResult

Lambda response format for API Gateway:

```ts theme={null}
type APIGatewayProxyResult = {
  statusCode: number
  statusDescription?: string
  body: string
  cookies?: string[]           // API Gateway v2 only
  isBase64Encoded: boolean
} & (WithHeaders | WithMultiValueHeaders)
```

### Request Context Types

#### ApiGatewayRequestContext

API Gateway REST API (v1) request context:

```ts theme={null}
interface ApiGatewayRequestContext {
  accountId: string
  apiId: string
  domainName: string
  httpMethod: string
  identity: Identity
  path: string
  requestId: string
  stage: string
  // ... additional fields
}
```

#### ApiGatewayRequestContextV2

API Gateway HTTP API (v2) and Function URLs request context:

```ts theme={null}
interface ApiGatewayRequestContextV2 {
  accountId: string
  apiId: string
  domainName: string
  http: {
    method: string
    path: string
    protocol: string
    sourceIp: string
    userAgent: string
  }
  requestId: string
  routeKey: string
  stage: string
  // ... additional fields
}
```

#### ALBRequestContext

Application Load Balancer request context:

```ts theme={null}
interface ALBRequestContext {
  elb: {
    targetGroupArn: string
  }
}
```

### LambdaContext

AWS Lambda runtime context:

```ts theme={null}
interface LambdaContext {
  callbackWaitsForEmptyEventLoop: boolean
  functionName: string
  functionVersion: string
  invokedFunctionArn: string
  memoryLimitInMB: string
  awsRequestId: string
  logGroupName: string
  logStreamName: string
  identity?: CognitoIdentity
  clientContext?: ClientContext
  getRemainingTimeInMillis(): number
}
```

## Accessing Lambda Context

The Lambda event and context are available through `c.env`:

```ts theme={null}
import { Hono } from 'hono'
import { handle } from 'hono/aws-lambda'
import type { LambdaEvent, LambdaContext } from 'hono/aws-lambda'

type Bindings = {
  event: LambdaEvent
  requestContext: ApiGatewayRequestContextV2
  lambdaContext: LambdaContext
}

const app = new Hono<{ Bindings: Bindings }>()

app.get('/lambda-info', (c) => {
  const { lambdaContext } = c.env
  
  return c.json({
    functionName: lambdaContext.functionName,
    requestId: lambdaContext.awsRequestId,
    remainingTime: lambdaContext.getRemainingTimeInMillis(),
    memoryLimit: lambdaContext.memoryLimitInMB
  })
})

export const handler = handle(app)
```

## Platform-Specific Notes

### Event Sources

The adapter automatically detects and handles:

* **API Gateway REST API (v1)**: Traditional REST APIs with resource-based routing
* **API Gateway HTTP API (v2)**: Lower latency, lower cost HTTP APIs
* **Lambda Function URLs**: Direct HTTPS endpoints for Lambda functions
* **Application Load Balancer**: ALB target integrations
* **VPC Lattice**: Service mesh integrations

### Binary Content

Binary responses are automatically base64 encoded based on:

1. Content-Type header (via `isContentTypeBinary` option)
2. Content-Encoding header (gzip, deflate, compress, br)

### Headers

* **Single-value headers**: Used by default and API Gateway v2
* **Multi-value headers**: Used when the event includes `multiValueHeaders`

### Cookies

* **API Gateway v2**: Uses the `cookies` array in the response
* **API Gateway v1**: Uses `multiValueHeaders['set-cookie']`
* **ALB**: Depends on multi-value headers configuration

## Deployment

### Using AWS SAM

```yaml theme={null}
# template.yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Resources:
  HonoFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs20.x
      Events:
        ApiEvent:
          Type: HttpApi
          Properties:
            Path: /{proxy+}
            Method: ANY
```

### Using AWS CDK

```ts theme={null}
import * as lambda from 'aws-cdk-lib/aws-lambda'
import * as apigateway from 'aws-cdk-lib/aws-apigatewayv2'
import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations'

const handler = new lambda.Function(this, 'HonoHandler', {
  runtime: lambda.Runtime.NODEJS_20_X,
  code: lambda.Code.fromAsset('dist'),
  handler: 'index.handler',
})

const httpApi = new apigateway.HttpApi(this, 'HonoApi', {
  defaultIntegration: new HttpLambdaIntegration('HonoIntegration', handler),
})
```

### Using Serverless Framework

```yaml theme={null}
# serverless.yml
service: hono-lambda

provider:
  name: aws
  runtime: nodejs20.x

functions:
  api:
    handler: index.handler
    events:
      - httpApi:
          path: /{proxy+}
          method: ANY
```

## See Also

* [AWS Lambda Documentation](https://docs.aws.amazon.com/lambda/)
* [API Gateway HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html)
* [Lambda Function URLs](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html)
* [Application Load Balancer](https://docs.aws.amazon.com/lambda/latest/dg/services-alb.html)