AWS lambda documentation change
Summary
Restructured documentation for Node.js layers, focusing on practical steps for packaging layer content, creating layers, and adding them to functions. Removed theoretical compatibility discussions and added concrete examples for npm packages and custom code.
Security assessment
The changes primarily reorganize content and provide clearer implementation steps. There is no mention of security vulnerabilities, patches, or explicit security-related guidance. The added notes about Linux compatibility and architecture targeting are standard runtime compatibility requirements, not security fixes.
Diff
diff --git a/lambda/latest/dg/nodejs-layers.md b/lambda/latest/dg/nodejs-layers.md index 191b5e39d..2e3a070f8 100644 --- a//lambda/latest/dg/nodejs-layers.md +++ b//lambda/latest/dg/nodejs-layers.md @@ -5 +5 @@ -PrerequisitesNode.js layer compatibility with the Lambda runtime environmentLayer paths for Node.js runtimesPackaging the layer contentCreating the layerAdding the layer to your function +Package your layer contentCreate the layer in LambdaAdd the layer to your functionSample app @@ -20,2 +19,0 @@ Use [Lambda layers](./chapter-layers.html) to package code and dependencies that -This topic contains steps and guidance on how to properly package and create a Node.js Lambda layer with external library dependencies. - @@ -24,3 +22 @@ This topic contains steps and guidance on how to properly package and create a N - * Prerequisites - - * Node.js layer compatibility with the Lambda runtime environment + * Package your layer content @@ -28 +24 @@ This topic contains steps and guidance on how to properly package and create a N - * Layer paths for Node.js runtimes + * Create the layer in Lambda @@ -30 +26 @@ This topic contains steps and guidance on how to properly package and create a N - * Packaging the layer content + * Add the layer to your function @@ -32 +28 @@ This topic contains steps and guidance on how to properly package and create a N - * Creating the layer + * Sample app @@ -34 +29,0 @@ This topic contains steps and guidance on how to properly package and create a N - * Adding the layer to your function @@ -37,0 +33 @@ This topic contains steps and guidance on how to properly package and create a N +## Package your layer content @@ -39 +35 @@ This topic contains steps and guidance on how to properly package and create a N -## Prerequisites +To create a layer, bundle your packages into a .zip file archive that meets the following requirements: @@ -41 +37 @@ This topic contains steps and guidance on how to properly package and create a N -To follow the steps in this section, you must have the following: + * Build the layer using the same Node.js version that you plan to use for the Lambda function. For example, if you build your layer using Node.js 22, use the Node.js 22 runtime for your function. @@ -43 +39 @@ To follow the steps in this section, you must have the following: - * [Node.js 22](https://nodejs.org/en/blog/release/v22.11.0) and the [npm](https://www.npmjs.com/) package manager. For more information about installing Node.js, see [Installing Node.js via package manager](https://nodejs.org/en/download/package-manager/) in the Node.js documentation. + * Your layer's .zip file must use one of these directory structures: @@ -45 +41 @@ To follow the steps in this section, you must have the following: - * [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + * `nodejs/node_modules` @@ -46,0 +43 @@ To follow the steps in this section, you must have the following: + * `nodejs/node`X`/node_modules` (where `X` is your Node.js version, for example `node22`) @@ -47,0 +45 @@ To follow the steps in this section, you must have the following: +For more information, see [Layer paths for each Lambda runtime](./packaging-layers.html#packaging-layers-paths). @@ -48,0 +47 @@ To follow the steps in this section, you must have the following: + * The packages in your layer must be compatible with Linux. Lambda functions run on Amazon Linux. @@ -50 +49 @@ To follow the steps in this section, you must have the following: -Throughout this topic, we reference the [layer-nodejs](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/layer-nodejs) sample application in the _aws-lambda-developer-guide_ GitHub repository. This application contains scripts that download a dependency and package it into a layer. The application also contains corresponding functions that use the dependency from the layer. After creating a layer, you can deploy and invoke the corresponding function to verify that everything works. This sample application uses the Node.js 22 runtime. If you add additional dependencies to your layer, they must be compatible with Node.js 22. + * If your layer includes native binaries or executable files, they must target the same [architecture](./foundation-arch.html) (x86_64 or arm64) as your function. @@ -52 +50,0 @@ Throughout this topic, we reference the [layer-nodejs](https://github.com/awsdoc -The `layer-nodejs` sample application will package the [lodash](https://www.npmjs.com/package/lodash) library into a Lambda layer. The `layer` directory contains the scripts to generate the layer. The `function` directory contains a sample function to test that the layer works. This document walks through how to create, package, deploy and test this layer. @@ -54 +51,0 @@ The `layer-nodejs` sample application will package the [lodash](https://www.npmj -## Node.js layer compatibility with the Lambda runtime environment @@ -56 +52,0 @@ The `layer-nodejs` sample application will package the [lodash](https://www.npmj -When you package code in a Node.js layer, you specify the Lambda runtime environments that the code is compatible with. To assess code compatibility with a runtime, consider what versions of Node.js, what operating systems, and what instruction set architectures the code is designed for. @@ -58 +54 @@ When you package code in a Node.js layer, you specify the Lambda runtime environ -Lambda Node.js runtimes specify their Node.js version and operating system. In this document, you will use the Node.js 22 runtime, which is based on AL2023. For more information about runtime versions, see [Supported runtimes](./lambda-runtimes.html#runtimes-supported). When you create a Lambda function, you specify the instruction set architecture. In this document, you will use the `arm64` architecture. For more information about architectures in Lambda, see [Selecting and configuring an instruction set architecture for your Lambda function](./foundation-arch.html). +You can create layers that contain either third-party Node.js libraries installed with `npm` (such as `axios` or `lodash`) or your own JavaScript modules. @@ -60 +56 @@ Lambda Node.js runtimes specify their Node.js version and operating system. In t -When you use code provided in a package, each package maintainer independently defines their compatibility. Most Node.js development is designed to work independently of operating system and instruction set architecture. Additionally, breaking incompatibilities with new Node.js versions are not that common. Expect to spend more of your time assessing compatibility between packages than assessing package compatibility with Node.js version, operating system, or instruction set architecture. +###### To create a layer using npm packages @@ -62 +58 @@ When you use code provided in a package, each package maintainer independently d -Sometimes Node.js packages include compiled code, which require you to consider operating system and instruction set architecture compatibility. If you do need to assess code compatibility for your packages, you will need to inspect the packages and their documentation. Packages in NPM can specify their compatibility through the `engines`, `os`, and `cpu` fields of their `package.json` manifest file. For more information about `package.json` files, see [package.json](https://docs.npmjs.com/cli/v10/configuring-npm/package-json) in the NPM documentation. + 1. Create the required directory structure and install packages directly into it: @@ -64 +60,2 @@ Sometimes Node.js packages include compiled code, which require you to consider -## Layer paths for Node.js runtimes + mkdir -p nodejs + npm install --prefix nodejs lodash axios @@ -66 +63 @@ Sometimes Node.js packages include compiled code, which require you to consider -When you add a layer to a function, Lambda loads the layer content into the execution environment. If your layer packages dependencies in specific folder paths, the Node.js execution environment will recognize the modules, and you can reference the modules from your function code. +This command installs the packages directly into the `nodejs/node_modules` directory, which is the structure that Lambda requires. @@ -68 +65 @@ When you add a layer to a function, Lambda loads the layer content into the exec -To ensure that your modules are picked up, package them into your layer .zip file in one of the following folder paths. These files are stored in `/opt`, and the folder paths are loaded into the `PATH` environment variable. +###### Note @@ -70 +67 @@ To ensure that your modules are picked up, package them into your layer .zip fil - * `nodejs/node_modules` +For packages with native dependencies or binary components (such as [sharp](https://www.npmjs.com/package/sharp) or [bcrypt](https://docs.aws.amazon.com/https://www.npmjs.com/package/bcrypt)), ensure that they're compatible with the Lambda Linux environment and your function's [architecture](./foundation-arch.html). You might need to use the `--platform` flag: @@ -72 +69 @@ To ensure that your modules are picked up, package them into your layer .zip fil - * `nodejs/node`X`/node_modules` + npm install --prefix nodejs --platform=linux --arch=x64 sharp @@ -73,0 +71 @@ To ensure that your modules are picked up, package them into your layer .zip fil +For more complex native dependencies, you might need to compile them in a Linux environment that matches the Lambda runtime. You can use Docker for this purpose. @@ -74,0 +73 @@ To ensure that your modules are picked up, package them into your layer .zip fil + 2. Zip the layer content: @@ -75,0 +75 @@ To ensure that your modules are picked up, package them into your layer .zip fil +Linux/macOS @@ -77 +76,0 @@ To ensure that your modules are picked up, package them into your layer .zip fil -For example, the resulting layer .zip file that you create in this tutorial has the following directory structure: @@ -78,0 +78 @@ For example, the resulting layer .zip file that you create in this tutorial has + zip -r layer.zip nodejs/ @@ -80,7 +80 @@ For example, the resulting layer .zip file that you create in this tutorial has - layer_content.zip - └ nodejs - └ node22 - └ node_modules - └ lodash - └ <other potential dependencies> - └ ... +PowerShell @@ -88 +81,0 @@ For example, the resulting layer .zip file that you create in this tutorial has -You will put the [`lodash`](https://www.npmjs.com/package/lodash) library in the `nodejs/node22/node_modules` directory. This ensures that Lambda can locate the library during function invocations. @@ -90 +83 @@ You will put the [`lodash`](https://www.npmjs.com/package/lodash) library in the -## Packaging the layer content + Compress-Archive -Path .\nodejs -DestinationPath .\layer.zip @@ -92 +85 @@ You will put the [`lodash`](https://www.npmjs.com/package/lodash) library in the -In this example, you package the `lodash` library in a layer .zip file. Complete the following steps to install and package the layer content. +The directory structure of your .zip file should look like this: @@ -94 +87,5 @@ In this example, you package the `lodash` library in a layer .zip file. Complete -###### To install and package your layer content + nodejs/ + └── node_modules/ + ├── lodash/ + ├── axios/ + └── (dependencies of the other packages) @@ -96 +93 @@ In this example, you package the `lodash` library in a layer .zip file. Complete - 1. Clone the [ aws-lambda-developer-guide](https://github.com/awsdocs/aws-lambda-developer-guide) repository from GitHub, which contains the sample code that you need in the `sample-apps/layer-nodejs` directory. +###### Note @@ -98 +95 @@ In this example, you package the `lodash` library in a layer .zip file. Complete - git clone https://github.com/awsdocs/aws-lambda-developer-guide.git +Make sure your .zip file includes the `nodejs` directory at the root level with `node_modules` inside it. This structure ensures that Lambda can locate and import your packages. @@ -100 +96,0 @@ In this example, you package the `lodash` library in a layer .zip file. Complete - 2. Navigate to the `layer` directory of the `layer-nodejs` sample app. This directory contains the scripts that you use to create and package the layer properly. @@ -102 +97,0 @@ In this example, you package the `lodash` library in a layer .zip file. Complete - cd aws-lambda-developer-guide/sample-apps/layer-nodejs/layer @@ -104 +98,0 @@ In this example, you package the `lodash` library in a layer .zip file. Complete - 3. Ensure the `package.json` file lists `lodash`. This file defines the dependencies that you want to include in the layer. You can update this file to include any dependencies that you want in your layer. @@ -106 +100 @@ In this example, you package the `lodash` library in a layer .zip file. Complete -###### Note +###### To create a layer using your own code @@ -108 +102 @@ In this example, you package the `lodash` library in a layer .zip file. Complete -The `package.json` used in this step is not stored or used with your dependencies after they are uploaded to a Lambda layer. It is only used in the layer packaging process, and does not specify a run command and compatibility as the file would in a Node.js application or published package. + 1. Create the required directory structure for your layer: @@ -110 +104 @@ The `package.json` used in this step is not stored or used with your dependencie - 4. Ensure that you have shell permission to run the scripts in the `layer` directory. + mkdir -p nodejs/node_modules/validator @@ -112 +106 @@ The `package.json` used in this step is not stored or used with your dependencie - chmod 744 1-install.sh && chmod 744 2-package.sh + 2. Create a `package.json` file for your custom module to define how it should be imported: @@ -114 +108 @@ The `package.json` used in this step is not stored or used with your dependencie - 5. Run the [1-install.sh](https://github.com/awsdocs/aws-lambda-developer-guide/blob/main/sample-apps/layer-nodejs/layer/1-install.sh) script using the following command: +###### Example package.json @@ -116 +110,6 @@ The `package.json` used in this step is not stored or used with your dependencie - ./1-install.sh + { + "name": "validator", + "version": "1.0.0", + "type": "module", + "main": "index.mjs" + } @@ -118 +117 @@ The `package.json` used in this step is not stored or used with your dependencie -This script runs `npm install`, which reads your `package.json` and downloads the dependencies defined inside of it. + 3. Create your JavaScript module file: @@ -120 +119 @@ This script runs `npm install`, which reads your `package.json` and downloads th -###### Example 1-install.sh +###### Example nodejs/node_modules/validator/index.mjs @@ -122 +121,3 @@ This script runs `npm install`, which reads your `package.json` and downloads th - npm install . + export function validateOrder(orderData) { + // Validates an order and returns formatted data + const requiredFields = ['productId', 'quantity']; @@ -124 +125,5 @@ This script runs `npm install`, which reads your `package.json` and downloads th - 6. Run the [2-package.sh](https://github.com/awsdocs/aws-lambda-developer-guide/blob/main/sample-apps/layer-nodejs/layer/2-package.sh) script using the following command: + // Check required fields + const missingFields = requiredFields.filter(field => !(field in orderData)); + if (missingFields.length > 0) { + throw new Error(`Missing required fields: ${missingFields.join(', ')}`); + } @@ -126 +131,5 @@ This script runs `npm install`, which reads your `package.json` and downloads th - ./2-package.sh + // Validate quantity + const quantity = orderData.quantity; + if (!Number.isInteger(quantity) || quantity < 1) { + throw new Error('Quantity must be a positive integer'); + } @@ -128 +137,7 @@ This script runs `npm install`, which reads your `package.json` and downloads th -This script copies the contents from the `node_modules` directory into a new directory named `nodejs/node22`. It then zips the contents of the `nodejs` directory into a file named `layer_content.zip`. This is the .zip file for your layer. You can unzip the file and verify that it contains the correct file structure, as shown in the Layer paths for Node.js runtimes section. + // Format and return the validated data + return { + productId: String(orderData.productId), + quantity: quantity, + shippingPriority: orderData.priority || 'standard' + }; + } @@ -130 +145,7 @@ This script copies the contents from the `node_modules` directory into a new dir -###### Example 2-package.sh + export function formatResponse(statusCode, body) { + // Formats the API response + return { + statusCode: statusCode, + body: JSON.stringify(body) + }; + } @@ -132,3 +153 @@ This script copies the contents from the `node_modules` directory into a new dir - mkdir -p nodejs/node22 - cp -r node_modules nodejs/node22/ - zip -r layer_content.zip nodejs + 4. Zip the layer content: @@ -135,0 +155 @@ This script copies the contents from the `node_modules` directory into a new dir +Linux/macOS @@ -137,0 +158 @@ This script copies the contents from the `node_modules` directory into a new dir