Configuring your application's dependencies on Elastic Beanstalk

Your application might have dependencies on some Node.js modules, such as the ones you specify in require() statements. These modules are stored in a node_modules directory. When your application runs, Node.js loads the modules from this directory. For more information, see Loading from node_modules folders in the Node.js documentation.

You can specify these module dependencies using a package.json file. If Elastic Beanstalk detects this file and a node_modules directory isn't present, Elastic Beanstalk runs npm install as the webapp user. The npm install command installs the dependencies in the node_modules directory, which Elastic Beanstalk creates beforehand. The npm install command accesses the packages listed in the package.json file from the public npm registry or other locations. For more information, see the npm Docs website.

If Elastic Beanstalk detects the node_modules directory, Elastic Beanstalk doesn't run npm install, even if a package.json file exists. Elastic Beanstalk assumes that the dependency packages are available in the node_modules directory for Node.js to access and load.

The following sections provide more information about establishing your Node.js module dependencies for your application.

Specifying Node.js dependencies with a package.json file

Include a package.json file in the root of your project source to specify dependency packages and to provide a start command. When a package.json file is present, and a node_modules directory isn't present in the root of your project source, Elastic Beanstalk runs npm install as the webapp user to install dependencies from the public npm registry. Elastic Beanstalk also uses the start command to start your application. For more information about the package.json file, see Specifying dependencies in a package.json file in the npm Docs website.

Use the scripts keyword to provide a start command. Currently, the scripts keyword is used instead of the legacy NodeCommand option in the aws:elasticbeanstalk:container:nodejs namespace.

{
    "name": "my-app",
    "version": "0.0.1",
    "private": true,
    "dependencies": {
      "ejs": "latest",
      "aws-sdk": "latest",
      "express": "latest",
      "body-parser": "latest"
    },
    "scripts": {
      "start": "node app.js"
    }
  }

Production mode and dev dependencies

To specify your dependencies in the package.json file use the dependencies and devDependencies attributes. The dependencies attribute designates packages required by your application in production. The devDependencies attribute designates packages that are only needed for local development and testing.

Elastic Beanstalk runs npm install as the webapp user with the following commands. The command options vary depending on the npm version included on platform branch that your application runs on.

Both of the commands listed above do not install the packages that are devDependencies.

If you need to install the devDependencies packages, set the NPM_USE_PRODUCTION environment property to false. With this setting we will not use the above options when running npm install. This will result in the devDependencies packages being installed.

SSH and HTTPS

Starting with the March 7, 2023 Amazon Linux 2 platform release, you can also use the SSH and HTTPS protocols to retrieve packages from a Git repository. Platform branch Node.js 16 supports both the SSH and HTTPS protocols. Node.js 14 only supports the HTTPS protocol.

    ...
    "dependencies": {
      "aws-sdk": "https://github.com/aws/aws-sdk-js.git",
      "aws-chime": "git+ssh://git@github.com:aws/amazon-chime-sdk-js.git"
    }

Versions and version ranges

Use the engines keyword in the package.json file to specify the Node.js version that you want your application to use. You can also specify a version range using npm notation. For more information about the syntax for version ranges, see Semantic Versioning using npm on the Node.js website. The engines keyword in the Node.js package.json file replaces the legacy NodeVersion option in the aws:elasticbeanstalk:container:nodejs namespace.

{
    ...
    "engines": { "node" : "14.16.0" }
  }

{
    ...
    "engines": { "node" : ">=10 <11" }
  }

When a version range is indicated, Elastic Beanstalk installs the latest Node.js version that the platform has available within the range. In this example, the range indicates that the version must be greater than or equal to version 10, but less than version 11. As a result, Elastic Beanstalk installs the latest Node.js version 10.x.y, which is available on the supported platform.

Be aware that you can only specify a Node.js version that corresponds with your platform branch. For example, if you're using the Node.js 16 platform branch, you can only specify a 16.x.y Node.js version. You can use the version range options supported by npm to allow for more flexibility. For valid Node.js versions for each platform branch, see Node.js in the AWS Elastic Beanstalk Platforms guide.

Including Node.js dependencies in a node_modules directory

To deploy dependency packages to environment instances together with your application code, include them in a directory that's named node_modules in the root of your project source. For more information, see Downloading and installing packages locally in the npm Docs website.

When you deploy a node_modules directory to an AL2023/AL2 Node.js platform version, Elastic Beanstalk assumes that you're providing your own dependency packages, and avoids installing dependencies that are specified in a package.json file. Node.js looks for dependencies in the node_modules directory. For more information, see Loading from node_modules Folders in the Node.js documentation.