Node.js CF-compatible CNB

Page last updated:

This topic describes using the Node.js Cloud Native Buildpack (CNB) to deploy your apps.

Cloud Native Buildpack Migration Guide

For strategies for migrating from the old Node.js buildpack to the new Node.js CNB.

Please see this guide

Specifying a Node Engine Version

The Node Engine CNB allows you to specify a version of Node.js to use during deployment. This version can be specified in a number of ways, including through .nvmrc, buildpack.yml, or package.json files. When specifying a version of the Node.js engine, you must choose a version that is available within the buildpack.

When you specify a version, the buildpack prioritizes the versions specified in each possible configuration location with the following precedence, from highest to lowest: buildpack.yml, package.json, .nvmrc.

Using buildpack.yml

To configure the buildpack to use Node.js v12.12.0 when deploying your app, include the values below in your buildpack.yml file:

---
nodejs:
  version: 12.12.0

Using package.json

If your apps use npm, you can specify the Node.js version your apps use during deployment by configuring the engines field in the package.json file. To configure the buildpack to use Node.js v12.12.0 when deploying your app, include the values below in your package.json file:

{
  "engines": {
    "node": "12.12.0"
  }
}

For more information about the engines configuration option in the package.json file, see the engines section of the npm-package.json topic in the NPM documentation.

Using .nvmrc

Node Version Manager is a common option for managing the Node.js version an app uses. To specify the Node.js version your apps use during deployment, include a .nvmrc file with the version number. For more information about the contents of a .nvmrc file, see .nvmrc in the Node Version Manager repository on GitHub.

Environment Variables

The Node.js CNB sets a number of environment variables during the build and launch phases of the app lifecycle. The sections below describe each environment variable, its impact on your app, and how to configure these variable with alternative settings.

MEMORY_AVAILABLE

The MEMORY_AVAILABLE environment variable reports the total amount of memory available to the app. The Node.js CNB calculates this value from the $VCAP_APPLICATION settings or 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-cnb
  • Phases: build
  • Value: production

NODE_HOME

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

  • Set by: node-engine-cnb
  • 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-cnb
  • Phases: build
  • Value: false

NPM_CONFIG_LOGLEVEL

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

  • Set by: node-engine-cnb
  • Phases: build
  • Value: “error”

NPM_CONFIG_PRODUCTION

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

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

PATH

The PATH environment variable appends the node_modules/.bin directory onto the node installation path.

  • Set by: yarn-cnb
  • Phases: build
  • Value: path to the node_modules/.bin directory

Heap Memory Optimization

Node.js limits the total size of all objects on the heap. Enabling the optimize-memory feature sets this value to three-quarters of the total memory available in the container. For example, if your app is limited to 1 GB when pushed, the heap of your Node.js app is limited to 768 MB.

Enable Memory Optimization

There are two ways to enable memory optimization: through your buildpack.yml file, and by using the OPTIMIZE_MEMORY environment variable.

Use the buildpack.yml

To enable memory optimization through your buildpack.yml file, add the values below to your buildpack.yml file:

---
nodejs:
  optimize-memory: true

Use the OPTIMIZE_MEMORY Environment Variable

To enable memory optimization through the OPTIMIZE_MEMORY environment variable, set it to true.

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 CNB fully supports. Including a package.json file in your app source code begins the NPM installation process. The sections below describe the NPM installation process.

NPM Installation Process

NPM supports several distinct methods for installing your package dependencies. Specifically, the Node.js CNB runs a combination of the npm install, npm rebuild, and npm ci commands to build your app with the right set of dependencies. When deciding which installation process to use, the Node.js CNB consults your app source code, looking for the presence of specific files or directories.

For more information about the npm install command, see npm-install in the NPM documentation. For more information about the npm rebuild command, see npm-rebuild in the NPM documentation. For more information about the npm ci command, see npm-ci in the NPM documentation.

These sections describe the files and directories you can include in your source code, and which installation process the Node.js CNB uses when these files and directories are present.

package-lock.json

The package-lock.json file is a machine-generated file the Node.js CNB creates during the npm install process. 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 the Node.js CNB installs during the npm install process. For more information, see the Node Modules section of the npm-folders topic in the NPM documentation.

npm-cache

he 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 a npm-cache directory:

  1. Navigate to your source code directory.

  2. Run:

    npm ci --cache npm-cache
    

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

Determining an Installation Process

The table below shows the process the Node.js CNB uses to determine an installation process for NPM packages. When a combination of the files and directories described in NPM Installation Process is present, the Node.js CNB uses an installation process that ensures the correct third-party dependencies are installed during the build process.

package-lock.json node_modules npm-cache Command
X X X npm install
X X npm install
X X npm rebuild
X npm rebuild
X X npm ci
X npm ci
X npm rebuild
npm ci

Determining Layer Reuse

To improve build times for apps, the NPM CNB 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 previous build results.

For npm rebuild, the CNB reuses previous build results if the node_modules directory included in the app source code has not changed since the prior build.

For npm ci, the CNB reuses previous build results 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 that the Node.js CNB fully supports. Including package.json and yarn.lock files in your app source code begins the Yarn installation process.

Yarn Installation Process

The Node.js CNB runs yarn install and yarn check to ensure that third-party dependencies are properly installed. Including a yarn.lock file in your app source code causes the Node.js CNB to use the Yarn installation process.

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.

Start Command

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