Deploy Hono on AWS

Deploy your Hono app on AWS with Lambda and API Gateway using the AWS CDK.

There are a few ways to deploy your Hono app on AWS:

1. Standard Lambda and API Gateway.
2. Node.js runtime container image on Lambda.
3. Bun runtime container image on Lambda.
4. One-click installation on your AWS account using Thunder console.

Deploy Hono on AWS Lambda + API Gateway

CDK Functions is a package that simplifies the deployment of Lambdas using the AWS Cloud Development Kit (CDK). It provides a straightforward way to deploy your Hono app to AWS Lambda and API Gateway.

1. Create a project

You can create a new Hono project using the following commands:

npm create hono@latest my-hono-app
cd my-hono-app

pnpm create hono my-hono-app
cd my-hono-app

bun create hono my-hono-app
cd my-hono-app

2. Initialize your project

Install the necessary dependencies and initialize your project:

npm i tsx aws-cdk-lib @thunderso/cdk-functions --save-dev

pnpm add -D tsx aws-cdk-lib @thunderso/cdk-functions

bun add -d tsx aws-cdk-lib @thunderso/cdk-functions

3. Create a CDK stack

Create a stack/index.ts file. Edit it to match your project:

import { App } from "aws-cdk-lib";
import { Runtime, Architecture } from 'aws-cdk-lib/aws-lambda';
import { FunctionStack, type FunctionProps } from '@thunder-so/cdk-functions';

const fnStack: FunctionProps = {
    env: {
        account: '4477996600XX',
        region: 'us-east-1',
    },
    application: 'hono',
    service: 'api',
    environment: 'dev',

    functionProps: {
        codeDir: 'dist',
        handler: 'index.handler',
    },
};

new FunctionStack(new App(),
    `${fnStack.application}-${fnStack.service}-${fnStack.environment}-stack`,
    fnStack
);

4. Deploy

Before you deploy, run your build script to generate artifacts in the dist directory.

npm run build

pnpm run build

bun run build

By running the following script, the CDK stack will be deployed to AWS.

npx cdk deploy --all --app="npx tsx stack/index.ts"

pnpm exec cdk deploy --all --app="pnpm exec tsx stack/index.ts"

npx cdk deploy --all --app="bunx tsx stack/index.ts"

When the deployment is complete, you will see the API Gateway URL in the output. You can access your Hono app at that URL.

For complete documentation, refer to the CDK Functions documentation.

Node.js runtime container image on Lambda

You can also deploy your Hono app on AWS Lambda using a Node.js container image. This method allows you to package your application and its dependencies into a Docker image, which can then be deployed to AWS Lambda.

1. Create a Dockerfile

Create a Dockerfile.node in the root directory to build your Hono app as a container image:

FROM public.ecr.aws/lambda/nodejs:22 AS base
WORKDIR ${LAMBDA_TASK_ROOT}

# Copy dist files
COPY . .

# Set the Lambda handler
CMD [ "index.handler" ]

2. Create/modify your CDK stack

Create a stack/node.ts file to define your CDK stack:

const fnStack: FunctionProps = {
    // ... other props

    functionProps: {
        codeDir: 'dist',
        dockerFile: 'Dockerfile.node',
    },
};

By running the following script, the CDK stack will be deployed to AWS.

npx cdk deploy --all --app="npx tsx stack/node.ts"

pnpm exec cdk deploy --all --app="pnpm exec tsx stack/node.ts"

npx cdk deploy --all --app="bunx tsx stack/node.ts"

Bun runtime container image on Lambda

You can also deploy your Hono app on AWS Lambda with custom Bun runtime.

1. Create a lambda handler

Create a lambda-bun.js file in the root directory to handle the Lambda function:

const { handler } = require('./index.js');

exports.fetch = handler;

2. Create a Dockerfile

Create a Dockerfile.bun in the root directory to build your Hono app as a container image:

# Builder image
FROM oven/bun:latest AS bun
WORKDIR /tmp

## Install the bun dependencies
RUN apt-get update && apt-get install -y curl
RUN curl -fsSL https://raw.githubusercontent.com/oven-sh/bun/main/packages/bun-lambda/runtime.ts -o /tmp/runtime.ts
RUN bun install aws4fetch
RUN bun build --compile runtime.ts --outfile bootstrap

# Runtime image
FROM public.ecr.aws/lambda/provided:al2023
WORKDIR ${LAMBDA_TASK_ROOT}

## Copy bun + bootstrap from the builder image
COPY --from=bun /usr/local/bin/bun /opt/bun
COPY --from=bun /tmp/bootstrap ${LAMBDA_RUNTIME_DIR}

## Copy dist files
COPY . .

# Set our handler method
CMD [ "lambda-bun.fetch" ]

3. Create/modify your CDK stack

Create a stack/bun.ts file to define your CDK stack:

const fnStack: FunctionProps = {
    // ... other props

    functionProps: {
        codeDir: 'dist',
        include: [
            'lambda-bun.js' // Include the Lambda handler file
        ],
        dockerFile: 'Dockerfile.bun',
    },
};

Deploy your Hono app using the following command:

npx cdk deploy --all --app="bunx tsx stack/bun.ts"