A custom runtime layer that runs Bun on AWS Lambda.

First, you will need to deploy the layer to your AWS account. Clone this repository and run the publish-layer script to get started. Note: the publish-layer script also builds the layer.

git clone git@github.com:oven-sh/bun.git
cd bun/packages/bun-lambda
bun install
bun run publish-layer

Once you publish the layer to your AWS account, you can create a Lambda function that uses the layer.

In addition to providing the Bun runtime itself, the Bun Lambda Layer also provides an event transformation so you can write your Bun function in a classic Bun server format. This allows you to also run your Lambda function as a local Bun server with bun run <handler-name>.ts. Here are some examples of how to write a Bun Lambda function:

When an event is triggered from API Gateway, the layer transforms the event payload into a Request. This means you can test your Lambda function locally using bun run, without any code changes.

export default {
  async fetch(request: Request): Promise<Response> {
    console.log(request.headers.get("x-amzn-function-arn"));
    // ...
    return new Response("Hello from Lambda!", {
      status: 200,
      headers: {
        "Content-Type": "text/plain",
      },
    });
  },
};

For non-HTTP events — S3, SQS, EventBridge, etc. — the event payload is the body of the Request.

export default {
  async fetch(request: Request): Promise<Response> {
    const event = await request.json();
    // ...
    return new Response();
  },
};

The final step is to upload your Bun handler. You can technically write the handler directly in the console if you wish, but if you want a full development environment, use the Bun toolkit. There are several ways you can choose to build and manage your artifacts, but follow these steps for a simple approach:

1. Run bun build <handler-entry>.[ts|js] --outfile ./dist/handler.js
2. Zip the /dist folder

Once you've written your Lambda function, you need to configure a new Lambda function to use Bun. The following steps apply to configuring in the console, CloudFormation, CDK, Terraform, or any other configuration management option for AWS:

1. Create the Lambda function
2. Set the Runtime to custom with Amazon Linux 2
3. Set the handler to .fetch (e.g. if your bundled Bun handler is at handler.js, set the handler as handler.fetch)
4. Set the architecture to whichever architecture you configured when you built/deployed the Lambda Layer
5. Attach the Lambda Layer to your new function
6. Upload the zip file from step 2. You can do this in the console directly, upload to S3 and set that as the location for the handler file in Lambda, or use something like CDK to manage this for you.

Builds a Lambda layer for Bun and saves it to a .zip file.

Example:

bun run build-layer -- \
  --arch x64 \
  --release canary \
  --output /path/to/layer.zip

Builds a Lambda layer for Bun then publishes it to your AWS account.

Example:

bun run publish-layer -- \
  --arch aarch64 \
  --release latest \
  --output /path/to/layer.zip \
  --region us-east-1