Building Lambda functions with Node.js - Amazon Lambda
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Building Lambda functions with Node.js

You can run JavaScript code with Node.js in Amazon Lambda. Lambda provides runtimes for Node.js that run your code to process events. Your code runs in an environment that includes the Amazon SDK for JavaScript, with credentials from an Amazon Identity and Access Management (IAM) role that you manage. To learn more about the SDK versions included with the Node.js runtimes, see Runtime-included SDK versions.

Lambda supports the following Node.js runtimes.

Name Identifier Operating system Deprecation date Block function create Block function update

Node.js 20


Amazon Linux 2023

Node.js 18


Amazon Linux 2

Node.js 16


Amazon Linux 2

Jun 12, 2024

Feb 28, 2025

Mar 31, 2025


Node.js 18 and later runtimes use Amazon SDK for JavaScript v3. To migrate a function from an earlier runtime, follow the migration workshop on GitHub. For more information about Amazon SDK for JavaScript version 3, see the Modular Amazon SDK for JavaScript is now generally available blog post.

To create a Node.js function
  1. Open the Lambda console.

  2. Choose Create function.

  3. Configure the following settings:

    • Function name: Enter a name for the function.

    • Runtime: Choose Node.js 20.x.

  4. Choose Create function.

  5. To configure a test event, choose Test.

  6. For Event name, enter test.

  7. Choose Save changes.

  8. To invoke the function, choose Test.

The console creates a Lambda function with a single source file named index.js or index.mjs. You can edit this file and add more files in the built-in code editor. To save your changes, choose Save. Then, to run your code, choose Test.


The Lambda console uses Amazon Cloud9 to provide an integrated development environment in the browser. You can also use Amazon Cloud9 to develop Lambda functions in your own environment. For more information, see Working with Amazon Lambda functions using the Amazon Toolkit in the Amazon Cloud9 user guide.

The index.js or index.mjs file exports a function named handler that takes an event object and a context object. This is the handler function that Lambda calls when the function is invoked. The Node.js function runtime gets invocation events from Lambda and passes them to the handler. In the function configuration, the handler value is index.handler.

When you save your function code, the Lambda console creates a .zip file archive deployment package. When you develop your function code outside of the console (using an IDE) you need to create a deployment package to upload your code to the Lambda function.


To get started with application development in your local environment, deploy one of the sample applications available in this guide's GitHub repository.

Sample Lambda applications in Node.js
  • blank-nodejs – A Node.js function that shows the use of logging, environment variables, Amazon X-Ray tracing, layers, unit tests and the Amazon SDK.

  • nodejs-apig – A function with a public API endpoint that processes an event from API Gateway and returns an HTTP response.

  • efs-nodejs – A function that uses an Amazon EFS file system in a Amazon VPC. This sample includes a VPC, file system, mount targets, and access point configured for use with Lambda.

The function runtime passes a context object to the handler, in addition to the invocation event. The context object contains additional information about the invocation, the function, and the execution environment. More information is available from environment variables.

Your Lambda function comes with a CloudWatch Logs log group. The function runtime sends details about each invocation to CloudWatch Logs. It relays any logs that your function outputs during invocation. If your function returns an error, Lambda formats the error and returns it to the invoker.

Node.js initialization

Node.js has a unique event loop model that causes its initialization behavior to be different from other runtimes. Specifically, Node.js uses a non-blocking I/O model that supports asynchronous operations. This model allows Node.js to perform efficiently for most workloads. For example, if a Node.js function makes a network call, that request may be designated as an asynchronous operation and placed into a callback queue. The function may continue to process other operations within the main call stack without getting blocked by waiting for the network call to return. Once the network call is completed, its callback is executed and then removed from the callback queue.

Some initialization tasks may run asynchronously. These asynchronous tasks are not guaranteed to complete execution prior to an invocation. For example, code that makes a network call to fetch a parameter from Amazon Parameter Store may not be complete by the time Lambda executes the handler function. As a result, the variable may be null during an invocation. To avoid this, ensure that variables and other asynchronous code are fully initialized before continuing with the rest of the function's core business logic.

Alternatively, you can designate your function code as an ES module, allowing you to use await at the top level of the file, outside the scope of your function handler. When you await every Promise, the asynchronous initialization code completes before handler invocations, maximizing the effectiveness of provisioned concurrency in reducing cold start latency. For more information and an example, see Using Node.js ES modules and top-level await in Amazon Lambda.

Designating a function handler as an ES module

By default, Lambda treats files with the .js suffix as CommonJS modules. Optionally, you can designate your code as an ES module. You can do this in two ways: specifying the type as module in the function's package.json file, or by using the .mjs file name extension. In the first approach, your function code treats all .js files as ES modules, while in the second scenario, only the file you specify with .mjs is an ES module. You can mix ES modules and CommonJS modules by naming them .mjs and .cjs respectively, as .mjs files are always ES modules and .cjs files are always CommonJS modules.

Lambda searches folders in the NODE_PATH environment variable when loading ES modules. You can load the Amazon SDK that's included in the runtime using ES module import statements. You can also load ES modules from layers.

Runtime-included SDK versions

The version of the Amazon SDK included in the Node.js runtime depends on the runtime version and your Amazon Web Services Region. To find the version of the SDK included in the runtime you're using, create a Lambda function with the following code.


The example code shown below for Node.js versions 18 and above uses CommonJS format. If you create the function in the Lambda console, be sure to rename the file containing the code to index.js.

Example Node.js 18 and above
const { version } = require("@aws-sdk/client-s3/package.json"); exports.handler = async () => ({ version });

This returns a response in the following format:

{ "version": "3.462.0" }

Using keep-alive for TCP connections

The default Node.js HTTP/HTTPS agent creates a new TCP connection for every new request. To avoid the cost of establishing new connections, you can use keepAlive: true to reuse connections that your function makes using the Amazon SDK for JavaScript. Keep-alive can reduce request times for Lambda functions that make multiple API calls using the SDK.

In the Amazon SDK for JavaScript 3.x, which is included in nodejs18.x and later Lambda runtimes, keep-alive is enabled by default. To disable keep-alive, see Reusing connections with keep-alive in Node.js in the Amazon SDK for JavaScript 3.x Developer Guide. For more information about using keep-alive, see HTTP keep-alive is on by default in modular Amazon SDK for JavaScript on the Amazon Developer Tools Blog.

CA certificate loading

For Node.js runtime versions up to Node.js 18, Lambda automatically loads Amazon-specific CA (certificate authority) certificates to make it easier for you to create functions that interact with other Amazon services. For example, Lambda includes the Amazon RDS certificates necessary for validating the server identity certificate installed on your Amazon RDS database. This behavior can have a performance impact during cold starts.

Starting with Node.js 20, Lambda no longer loads additional CA certificates by default. The Node.js 20 runtime contains a certificate file with all Amazon CA certificates located at /var/runtime/ca-cert.pem. To restore the same behavior from Node.js 18 and earlier runtimes, set the NODE_EXTRA_CA_CERTS environment variable to /var/runtime/ca-cert.pem.

For optimal performance, we recommend bundling only the certificates that you need with your deployment package and loading them via the NODE_EXTRA_CA_CERTS environment variable. The certificates file should consist of one or more trusted root or intermediate CA certificates in PEM format. For example, for RDS, include the required certificates alongside your code as certificates/rds.pem. Then, load the certificates by setting NODE_EXTRA_CA_CERTS to /var/task/certificates/rds.pem.