Node.js Buildpack Reference

This reference documentation offers an in-depth description of the behavior and configuration options of the Paketo Node.js Buildpack. For explanations of how to use the buildpack for several common use-cases, see the Paketo Node.js Buildpack How To documentation.

Supported Dependencies

The Node.js buildpack supports several versions of Node.js. For more details on the specific versions supported in a given buildpack version, see the release notes.

Supported Service Bindings

The Node.js buildpack can be configured using service bindings.

Buildpack-Set Environment Variables

The Node.js buildpack sets a number of environment variables during the build and launch phases of the app lifecycle. The sections below describe each environment variable and its impact on your app.

MEMORY_AVAILABLE

The MEMORY_AVAILABLE environment variable reports the total amount of memory available to the app. The Node.js buildpack calculates this value from the limits specified by the operating system in /sys/fs/cgroup/memory/memory.limit_in_bytes.

• Set by: profile.d
• Phases: launch
• Value: non-negative integer

NODE_ENV

The NODE_ENV environment variable specifies the environment in which the app runs.

• Set by: node-engine buildpack
• Phases: build
• Value: production

NODE_HOME

The NODE_HOME environment variable sets the path to the node installation.

• Set by: node-engine buildpack
• Phases: build
• Value: path to the node installation

NODE_VERBOSE

The NODE_VERBOSE environment variable adjusts the amount of logging output from NPM during installs.

• Set by: node-engine buildpack
• Phases: build
• Value: false

NPM_CONFIG_LOGLEVEL

The NPM_CONFIG_LOGLEVEL environment variable adjusts the level of logging NPM uses.

• Set by: npm-install buildpack
• Phases: build
• Value: “error”

NPM_CONFIG_PRODUCTION

The NPM_CONFIG_PRODUCTION environment variable installs only production dependencies if NPM install is used.

• Set by: npm-install buildpack
• Phases: build
• Value: false

PATH

The node_modules/.bin directory is appended onto the PATH environment variable

• Set by: yarn-install or npm-install buildpacks
• Phases: build
• Value: path to the node_modules/.bin directory

Package Management with NPM

Many Node.js apps require a number of third-party libraries to perform common tasks and behaviors. NPM is an option for managing these third-party dependencies that the Node.js buildpack fully supports. Including a package.json file in your app source code triggers the NPM installation process. The sections below describe the NPM installation process run by the buildpack.

NPM Installation Process

NPM supports several distinct methods for installing your package dependencies. Specifically, the Node.js buildpack runs either the npm install, npm rebuild, or npm ci commands to build your app with the right set of dependencies. When deciding which installation process to use, the Node.js buildpack consults your app source code, looking for the presence of specific files or directories. The installation process used also determines how the Node.js buildpack will reuse layers when rebuilding your app.

The table below shows the process the Node.js buildpack uses to determine an installation process for NPM packages. When a combination of the files and directories listed in the table below are present in your app source code, the Node.js buildpack uses an installation process that ensures the correct third-party dependencies are installed during the build process.

The following sections give more information about the files listed in the table above, including how to generate them, if desired.

package-lock.json

The package-lock.json file is generated by running npm install. For more information, see npm-package-lock.json in the NPM documentation.

node_modules

The node_modules directory contains vendored copies of all the packages installed by the npm install process. For more information, see the Node Modules section of the npm-folders topic in the NPM documentation.

npm-cache

The npm-cache directory contains a content-addressable cache that stores all HTTP-request- and package-related data. Additionally, including a cache ensures that the app can be built entirely offline.

To populate an npm-cache directory:

1. Navigate to your source code directory.
2. Run:

   npm ci --cache npm-cache
   

   

   Copied!

For more information about the NPM cache, see npm-cache in the NPM documentation.

Determining Node Modules Layer Reuse

To improve build times for apps, the Node.js buildpack has a method for reusing the build results from previous builds. When the CNB determines that a portion of the build process can be reused from a previous build, the CNB uses the previous result. Each installation process uses a different method for determining whether the CNB can reuse a previous build result.

For npm install, the CNB never reuses a node_modules directory from previous builds.

For npm rebuild, the CNB can reuse a node_modules directory from a previous build if the included node_modules directory in the app source code has not changed since the prior build.

For npm ci, the CNB can reuse a node_modules directory from a previous build if the package-lock.json file included in the app source code has not changed since the prior build.

Package Management with Yarn

Many Node.js apps require a number of third-party libraries to perform common tasks and behaviors. Yarn is an alternative option to NPM for managing these third-party dependencies. Including package.json and yarn.lock files in your app source code triggers the Yarn installation process.

Yarn Installation Process

The Node.js buildpack runs yarn install and yarn check to ensure that third-party dependencies are properly installed. The yarn.lock file contains a fully resolved set of package dependencies that Yarn manages. For more information, see yarn.lock in the Yarn documentation.

Yarn Start Command

As part of the build process, the Node.js buildpack determines a start command for your app. The start command differs depending on which package management tooling the Node.js buildpack uses. If the Node.js buildpack uses yarn to install packages, the start command is yarn start.

Determining the Start Command

As part of the build process, the Node.js buildpack determines a start command for your app. The start command differs depending on which package management tooling the Node.js buildpack uses. If the Node.js buildpack uses npm or yarn to install packages, the start command is generated from the contents of package.json.

Projects Without Package Management

The Node.js buildpack also supports simple apps that do not require third-party packages.

Start Command

If no package manager is detected, the Node.js buildpack will look for four generic entrypoint JavaScript files, in this order:

• server.js
• app.js
• main.js
• index.js

When the buildpack finds one of these, it will consider that the app’s entrypoint and set the app image’s start command to node <entrypoint filename>.

Software Bill of Materials

The Node.js buildpack supports the full software bill of materials (SBOM) in Syft, CycloneDX, SPDX, and Paketo-specific formats.

The node module SBOM entries provide a full picture of the packages on the final app image. The purl field is especially helpful to locate where on the NPM Registry a module came from. Check out the Access the Software Bill of Materials guide for more information about how to retrieve the SBOM for your Node.js app image.