Define Lambda function handler in TypeScript

The Lambda function handler is the method in your function code that processes events. When your function is invoked, Lambda runs the handler method. Your function runs until the handler returns a response, exits, or times out.

This page describes how to work with Lambda function handlers in TypeScript, including options for project setup, naming conventions, and best practices. This page also includes an example of a TypeScript Lambda function that takes in information about an order, produces a text file receipt, and puts this file in an Amazon Simple Storage Service (Amazon S3) bucket. For information about how to deploy your function after writing it, see Deploy transpiled TypeScript code in Lambda with .zip file archives or Deploy transpiled TypeScript code in Lambda with container images.

Setting up your TypeScript project

Use a local integrated development environment (IDE) or text editor to write your TypeScript function code. You can’t create TypeScript code on the Lambda console.

There are multiple ways to initialize a TypeScript Lambda project. For example, you can create a project using npm, create an AWS SAM application, or create an AWS CDK application. To create the project using npm:

npm init

Your function code lives in a .ts file, which you transpile into a JavaScript file at build time. You can use either esbuild or Microsoft's TypeScript compiler (tsc) to transpile your TypeScript code into JavaScript. To use esbuild, add it as a development dependency:

npm install -D esbuild

A typical TypeScript Lambda function project follows this general structure:

/project-root
  ├── index.ts - Contains main handler
  ├── dist/ - Contains compiled JavaScript
  ├── package.json - Project metadata and dependencies
  ├── package-lock.json - Dependency lock file
  ├── tsconfig.json - TypeScript configuration
  └── node_modules/ - Installed dependencies

Example TypeScript Lambda function code

The following example Lambda function code takes in information about an order, produces a text file receipt, and puts this file in an Amazon S3 bucket. This example defines a custom event type (OrderEvent). To learn how to import type definitions for AWS event sources, see Type definitions for Lambda.

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';

// Initialize the S3 client outside the handler for reuse
const s3Client = new S3Client();

// Define the shape of the input event
type OrderEvent = {
    order_id: string;
    amount: number;
    item: string;
}

/**
 * Lambda handler for processing orders and storing receipts in S3.
 */
export const handler = async (event: OrderEvent): Promise<string> => {
    try {
        // Access environment variables
        const bucketName = process.env.RECEIPT_BUCKET;
        if (!bucketName) {
            throw new Error('RECEIPT_BUCKET environment variable is not set');
        }

        // Create the receipt content and key destination
        const receiptContent = `OrderID: ${event.order_id}\nAmount: $${event.amount.toFixed(2)}\nItem: ${event.item}`;
        const key = `receipts/${event.order_id}.txt`;

        // Upload the receipt to S3
        await uploadReceiptToS3(bucketName, key, receiptContent);

        console.log(`Successfully processed order ${event.order_id} and stored receipt in S3 bucket ${bucketName}`);
        return 'Success';
    } catch (error) {
        console.error(`Failed to process order: ${error instanceof Error ? error.message : 'Unknown error'}`);
        throw error;
    }
};

/**
 * Helper function to upload receipt to S3
 */
async function uploadReceiptToS3(bucketName: string, key: string, receiptContent: string): Promise<void> {
    try {
        const command = new PutObjectCommand({
            Bucket: bucketName,
            Key: key,
            Body: receiptContent
        });

        await s3Client.send(command);
    } catch (error) {
        throw new Error(`Failed to upload receipt to S3: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
}

This index.ts file contains the following sections of code:

For this function to work properly, its execution role must allow the s3:PutObject action. Also, ensure that you define the RECEIPT_BUCKET environment variable. After a successful invocation, the Amazon S3 bucket should contain a receipt file.

Handler naming conventions

When you configure a function, the value of the Handler setting is the file name and the name of the exported handler method, separated by a dot. The default for functions created in the console and for examples in this guide is index.handler. This indicates the handler method that's exported from the index.js or index.mjs file.

If you create a function in the console using a different file name or function handler name, you must edit the default handler name.

Defining and accessing the input event object

JSON is the most common and standard input format for Lambda functions. In this example, the function expects an input similar to the following:

{
    "order_id": "12345",
    "amount": 199.99,
    "item": "Wireless Headphones"
}

When working with Lambda functions in TypeScript, you can define the shape of the input event using a type or interface. In this example, we define the event structure using a type:

type OrderEvent = {
    order_id: string;
    amount: number;
    item: string;
}

After you define the type or interface, use it in your handler's signature to ensure type safety:

export const handler = async (event: OrderEvent): Promise<string> => {

During compilation, TypeScript validates that the event object contains the required fields with the correct types. For example, the TypeScript compiler reports an error if you try to use event.order_id as a number or event.amount as a string.

Valid handler patterns for TypeScript functions

We recommend that you use async/await to declare the function handler instead of using callbacks. Async/await is a concise and readable way to write asynchronous code, without the need for nested callbacks or chaining promises. With async/await, you can write code that reads like synchronous code, while still being asynchronous and non-blocking.

The examples in this section use the S3Event type. However, you can use any other AWS event types in the @types/aws-lambda package, or define your own event type. To use types from @types/aws-lambda:

Using async/await (recommended)

The async keyword marks a function as asynchronous, and the await keyword pauses the execution of the function until a Promise is resolved. The handler accepts the following arguments:

Here are the valid signatures for the async/await pattern:

Using callbacks

Callback handlers can use the event, context, and callback arguments. The callback argument expects an Error and a response, which must be JSON-serializable.

Here are the valid signatures for the callback handler pattern:

The function continues to execute until the event loop is empty or the function times out. The response isn't sent to the invoker until all event loop tasks are finished. If the function times out, an error is returned instead. You can configure the runtime to send the response immediately by setting context.callbackWaitsForEmptyEventLoop to false.

import { Context, APIGatewayProxyCallback, APIGatewayEvent } from 'aws-lambda';

export const lambdaHandler = (event: APIGatewayEvent, context: Context, callback: APIGatewayProxyCallback): void => {
    console.log(`Event: ${JSON.stringify(event, null, 2)}`);
    console.log(`Context: ${JSON.stringify(context, null, 2)}`);
    callback(null, {
        statusCode: 200,
        body: JSON.stringify({
            message: 'hello world',
        }),
    });
};

Using the SDK for JavaScript v3 in your handler

Often, you’ll use Lambda functions to interact with or make updates to other AWS resources. The simplest way to interface with these resources is to use the AWS SDK for JavaScript. All supported Lambda Node.js runtimes include the SDK for JavaScript version 3. However, we strongly recommend that you include the AWS SDK clients that you need in your deployment package. This maximizes backward compatibility during future Lambda runtime updates.

To add SDK dependencies to your function, use the npm install command for the specific SDK clients that you need. In the example code, we used the Amazon S3 client. Add this dependency by running the following command in the directory that contains your package.json file:

npm install @aws-sdk/client-s3

In the function code, import the client and commands that you need, as the example function demonstrates:

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';

Then, initialize an Amazon S3 client:

const s3Client = new S3Client();

In this example, we initialized our Amazon S3 client outside of the main handler function to avoid having to initialize it every time we invoke our function. After you initialize your SDK client, you can then use it to make API calls for that AWS service. The example code calls the Amazon S3 PutObject API action as follows:

const command = new PutObjectCommand({
    Bucket: bucketName,
    Key: key,
    Body: receiptContent
});

Accessing environment variables

In your handler code, you can reference any environment variables by using process.env. In this example, we reference the defined RECEIPT_BUCKET environment variable using the following lines of code:

// Access environment variables
const bucketName = process.env.RECEIPT_BUCKET;
if (!bucketName) {
    throw new Error('RECEIPT_BUCKET environment variable is not set');
}

Using global state

Lambda runs your static code during the initialization phase before invoking your function for the first time. Resources created during initialization stay in memory between invocations, so you can avoid having to create them every time you invoke your function.

In the example code, the S3 client initialization code is outside the handler. The runtime initializes the client before the function handles its first event, and the client remains available for reuse across all invocations.

Code best practices for TypeScript Lambda functions

Follow these guidelines when building Lambda functions: