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

Lambda supports the following Node.js runtimes.

The console creates a Lambda function with a single source file namedindex.mjs. You can edit this file and add more files in the built-in code editor. In theDEPLOY section, chooseDeploy to update your function's code. Then, to run your code, chooseCreate test event in theTEST EVENTS section.

Theindex.mjs file exports a function namedhandler that takes an event object and a context object. This is thehandler 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 isindex.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 tocreate a deployment package to upload your code to the Lambda function.

The function runtime passes a context object to the handler, in addition to the invocation event. Thecontext 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 anylogs 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 AWS 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. There can also be a delay betweenINIT andINVOKE which can trigger errors in time-sensitive operations. In particular, AWS service calls can rely on time-sensitive request signatures, resulting in service call failures if the call is not completed during theINIT phase.

To avoid this, we recommend deploying your code as an ECMAScript module (ES module), and using top-levelawait to ensure all initialization is completed during the functionINIT phase. This ensures initialization tasks are completed before handler invocations, avoids delays betweenINIT andINVOKE disrupting time-sensitive operations, and also maximizes the effectiveness ofprovisioned concurrency in reducing cold start latency. For more information and an example, seeUsing Node.js ES modules and top-level await in AWS 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 thetype asmodule in the function'spackage.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 theNODE_PATH environment variable when loading ES modules. You can load the AWS SDK that's included in the runtime using ES moduleimport statements. You can also load ES modules fromlayers.

ES module example

Example – ES module handler

const url = "https://aws.amazon.com/";export const handler = async(event) =>{    try{        const res = await fetch(url);        console.info("status", res.status);        return res.status;    }    catch (e){        console.error(e);        return 500;    }};

CommonJS module example

Example – CommonJS module handler

const https = require("https");let url = "https://aws.amazon.com/";exports.handler = async function (event){  let statusCode;  await new Promise(function (resolve, reject){    https.get(url, (res) =>{        statusCode = res.statusCode;        resolve(statusCode);      }).on("error", (e) =>{        reject(Error(e));      });  });  console.log(statusCode);  return statusCode;};

Runtime-included SDK versions

Allsupported Lambda Node.js runtimes include a specific minor version of the AWS SDK for JavaScript v3, not thelatest version. The specific minor version that's included in the runtime depends on the runtime version and your AWS Region. To find the specific version of the SDK included in the runtime that you're using, create a Lambda function with the following code.

import packageJson from '@aws-sdk/client-s3/package.json' with{ type: 'json' };export const handler = async () => ({ version: packageJson.version });

{  "version": "3.632.0"}

For more information, seeUsing the SDK for JavaScript v3 in your handler.

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, keep-alive is enabled by default innodejs18.x and later Lambda runtimes. Keep-alive can reduce request times for Lambda functions that make multiple API calls using the SDK.

To disable keep-alive, seeReusing connections with keep-alive in Node.js in theAWS SDK for JavaScript 3.x Developer Guide. For more information about using keep-alive, seeHTTP keep-alive is on by default in modular AWS SDK for JavaScript on the AWS 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 AWS services. For example, Lambda includes the Amazon RDS certificates necessary for validating theserver 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 theNODE_EXTRA_CA_CERTSenvironment 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 theNODE_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 ascertificates/rds.pem. Then, load the certificates by settingNODE_EXTRA_CA_CERTS to/var/task/certificates/rds.pem.

Thanks for letting us know we're doing a good job!

If you've got a moment, please tell us what we did right so we can do more of it.

Thanks for letting us know this page needs work. We're sorry we let you down.

If you've got a moment, please tell us how we can make the documentation better.