How do I use layers to integrate the latest version of the AWS SDK for JavaScript into my Node.js Lambda function?

Short description

To integrate the latest version of an AWS SDK into your Lambda function's deployment package, create a Lambda layer. Then, add the layer to your function. To create a Lambda layer and add it to your function, use either the AWS Command Line Interface (AWS CLI) or the Lambda console.

Note: For Node.js versions 16 and earlier, the Lambda Node.js runtimes included the AWS SDK for JavaScript version 2. For Node.js versions 18 and later, the Lambda Node.js runtime includes the AWS SDK for JavaScript version 3. For more information, see Node.js 18.x runtime now available in AWS Lambda.

For a complete list of runtimes and the AWS SDK versions that Lambda uses, see Lambda runtimes.

Note: The following resolution increases the size of your function's deployment package. For information on Lambda storage quotas, see Lambda quotas.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

(Optional) Confirm the AWS SDK version that your function uses

To confirm the AWS SDK version that your function uses, complete the following steps:

Note: Use this method only for Node.js versions 16 and earlier. 

1. Create a function in the Lambda console.

2. Update the function's code to return the version of the AWS SDK that the function uses when you invoke the function:

   const AWS = require('aws-sdk')   
   exports.handler = async (event) => {  
   return AWS.VERSION;  
   };

3. Invoke your function.

4. Compare the version of the AWS SDK that your function returned with the latest version of the AWS SDK that's listed in the AWS SDK documentation.

Install and package the latest version of the AWS SDK

Note: Deployment packages must be compatible with the Lambda runtime that you use. It's a best practice to use the same operating system (OS) for your runtime that's specified in Lambda runtimes. For example, launch a compatible Amazon Elastic Compute Cloud (Amazon EC2) instance.

In a local, Lambda-compatible development environment, complete the following steps:

1. Run the following command to create a working directory:

   mkdir -p aws-sdk-layer/nodejs

2. Run the following command to change to the working directory:

   cd aws-sdk-layer/nodejs

3. Install the AWS SDK for your Node.js runtime version:
   Node.js 16 and earlier (AWS SDK version 2)
   To install the latest version of the AWS SDK version 2, use an Amazon Linux 2 compatible instance to run the following command:

   npm install aws-sdk

   For more information, see Tutorial: Setting up Node.js on an Amazon EC2 instance.

   Note: It's a best practice to use an Amazon Linux 2 environment when you develop Lambda resources.

   -or-

   If you use a Windows or macOS OS for development, then use Docker to run the following command:

   docker run --entrypoint "" -v "$PWD":/var/task "public.ecr.aws/lambda/nodejs:<version>" /bin/sh -c "npm install aws-sdk; exit"

   Note: Before you run the command, make sure that you're using the most recent version of Docker on the Docker website.

   Node.js 18 and later (AWS SDK version 3)

   See Installing the SDK for JavaScript.

   If you import an AWS SDK command that doesn't exist in the SDK version that's embedded in Lambda, then you might receive the following error:

   "Runtime.UserCodeSyntaxError "Named export not found" The requested module is a CommonJS module"

   In this case, install the specific package so that you can use it within your function. For example, you use the following import statement:

   import {DeleteQueueCommand} from "@aws-sdk/client-connect";

   In this case, install the updated client so that you can use the specific package within your function.

   For example, you use the following import statement in a Lambda function with Node.js version 18 or later:

   import {DeleteQueueCommand} from "@aws-sdk/client-connect";

   If this package isn’t in your current AWS SDK version, then you receive the following error in your logs:

   ""errorType": "Runtime.UserCodeSyntaxError",
       "errorMessage": "SyntaxError: Named export 'DeleteQueueCommand' not found. The requested module '@aws-sdk/client-connect' is a CommonJS module, which may not support all module.exports as named exports.\nCommonJS modules can always be imported via the default export, for example using:\n\nimport pkg from '@aws-sdk/client-connect';\nconst {DeleteQueueCommand} = pkg;\n","

   To include the DeleteQueueCommand package and resolve this error, install the newest version of the client:

   npm install @aws-sdk/client-connect  
   

4. Create a .zip file to upload to your Lambda layer:

   zip -r ../package.zip ../

5. (Optional) Verify the version of the AWS SDK that you installed:

   cat package-lock.json

   You get an output similar to the following example:

   {  "requires": true,  
     "lockfileVersion": 1,  
     "dependencies": {  
       "aws-sdk": {  
         "version": "2.888.0",  
   ...

Use the AWS CLI to create a Lambda layer and add it to your function

1. To create a new Lambda layer that includes the latest version of the AWS SDK that you want to use, run the following publish-layer-version command:

   Note: Replace node_sdk with your layer's name and My layer with a description of the layer. Also, replace the compatible-runtimes value with the runtime that you use and region with the AWS Region that your function and layer are in.

   aws lambda publish-layer-version --layer-name node_sdk --description "My layer" --license-info "MIT" --compatible-runtimes --zip-file fileb://../package.zip --region

   Note the LayerVersionArn value that's in the command output to use in the next step.

2. To add the layer to your function, run the following update-function-configuration command:

   Note: Replace my-function with the name of your function, arn:aws:lambda:us-east-2:123456789012:layer:node_sdk:1 with the LayerVersionArn value from your output, and region with your Region.

   aws lambda update-function-configuration --function-name my-function --layers arn:aws:lambda:us-east-2:123456789012:layer:node_sdk:1 --region

   For more information, see Working with Lambda layers.

Use the Lambda console to create a Lambda layer and add it to your function

1. Open the Layers page in the Lambda console.
2. Choose Create layer. Then, enter the following values:
   For Name, enter a name for the new layer.
   (Optional) For Description - optional, enter a description for the layer.
   Choose Upload a .zip file.
   Choose Upload. Then, choose the name of your deployment package .zip file.
   (Optional) For Compatible runtimes - optional, choose one or more compatible runtimes. 
   (Optional) For License - optional, enter any applicable software license information for the layer.
3. Choose Create.
4. Open the Functions page in the Lambda console, and then choose the name of the function that you want to add the layer to.
5. Below Function overview, choose Layers.
6. Choose Add a layer.
7. Under Choose a layer, choose Custom layers. Then, choose the following values:
   The name of the layer
   The version of the layer
8. Choose Add.

(Optional) Test the setup

Complete the steps in the (Optional) Confirm the AWS SDK version that your function uses section to invoke your function. The function returns the version of the AWS SDK that it uses.

You can also verify the latest version of the AWS SDK in the CHANGELOG file of the AWS SDK that you use. For more information, see Changelog for AWS SDK for JavaScript or Changelog for AWS SDK V3 for Javascript on the GitHub website.

Related information

Lambda programming model 

Best practices for working with AWS Lambda functions

How do I build a Lambda deployment package for Node.js?