Tanzu Buildpacks services

Use the Tanzu Node.js Buildpack

Last Updated December 15, 2025

This topic tells you how to use the Tanzu Node.js Buildpack.

The Tanzu Node.js Buildpack supports several popular configurations for Node.js apps.

Specify a Node Engine Version

The Node Engine Cloud Native Buildpack (CNB) allows you to specify a version of Node.js to use during deployment. You can specify the version in a number of ways, but you must choose a version that is available within the buildpack.

The buildpack prioritizes the versions specified in each possible configuration location with the following precedence, from highest to lowest:

  1. BP_NODE_VERSION
  2. package.json
  3. .nvmrc
  4. .node-version

Specify the Version Using BP_NODE_VERSION

To configure the buildpack to use, for example, Node.js v12.12.0 when deploying your app, set the following environment variable at build time. You can either set it directly by configuring the spec.build.env field on Tanzu Application Platform, or set it through a project.toml file.

For example:

BP_NODE_VERSION="12.12.0"

Specify the Version Using the package.json File

If your apps use npm or yarn, you can specify the Node.js version your apps use during deployment by configuring the engines field in the package.json file. For example, to configure the buildpack to use Node.js v12.12.0 when deploying your app, include the following values 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 NPM documentation.

Specify the Version 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.

Specify the Version Using .node-version

.node-version is another common option that is compatible with Node.js version managers such as asdf and nodenv. You can use a .node-version file to set the Node.js version that your apps use during deployment, according to one of the following formats:

12.12.0

OR

v12.12.0

OR

12.12

Enable 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.

To enable memory optimization, set BP_NODE_OPTIMIZE_MEMORY environment variable to true during build.

Specify a Project Directory

To specify a subdirectory to be used as the root of the app, set the BP_NODE_PROJECT_PATH environment variable at build time either directly or through a project.toml file. This might be useful if your app is a part of a monorepo.

For example, if your project has the following structure:

.
├── go-app
│   ├── go.mod
│   └── main.go
└── node-app
    ├── file.js
    ├── index.js
    └── package.json

you can set the following at build time:

$BP_NODE_PROJECT_PATH=node-app

Specify Scripts to be Run

To specify scripts inside package.json you want to run, use the BP_NODE_RUN_SCRIPTS environment variable at build time either directly or through a project.toml file.

The value of the variable must be a comma separated list of script names listed in the app's package.json.

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 triggers the NPM installation process. The following sections 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 CNB 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 CNB consults your app source code, looking for the presence of specific files or directories. The installation process used also decides how the Node.js CNB reuses layers when rebuilding your app.

The following table shows the process the Node.js CNB uses to select an installation process for NPM packages. When a combination of the files and directories listed in the following table are present in your app source code, 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

The following list gives more information about the files listed in this table, including how to generate them.

  • package-lock.json:

    The package-lock.json file is generated by running npm install. For more information, see 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 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

    For more information about the NPM cache, see the NPM documentation.

Node Modules Layer Reuse

To improve build times for apps, the Node.js CNB has a method for reusing the build results from previous builds. When the CNB discovers 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 deciding 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 previous build.

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

NPM Start Command

As part of the build process, the Node.js CNB selects 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 to install packages, the start command is npm start.

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 CNB 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 the Yarn documentation.

Yarn Start Command

As part of the build process, the Node.js CNB selects 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 yarn to install packages, the start command is yarn start.

Build an App Without Package Management

The Node.js buildpack supports building apps without node_modules or a package.json. It detects this type of app automatically, by looking for one of these four files in the root of your application directory:

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

Specify A Custom Entrypoint

If your app's entrypoint file is not one of the four files the buildpack can detect, specify a different filename or path by setting the BP_LAUNCHPOINT environment variable at build time. For example:

BP_LAUNCHPOINT="./src/launchpoint.js"

The image produced by the build runs node src/launchpoint.js as its start command.

Build and Serve a Frontend Framework App

If you are using a framework that generates a static site from JavaScript source code such as React, Vue, or Angular, you can use the Tanzu Web Servers buildpack to build the static assets and automatically configure a web server.

Enable Process Reloading

By default, your Node.js server is the only process running in your application container at runtime. You can enable restarting the server process when files in the app's working directory change, which might facilitate a shorter feedback loop for iterating on code changes.

Using BP_LIVE_RELOAD_ENABLED

To enable processes that can be reloaded, set the $BP_LIVE_RELOAD_ENABLED environment variable at build time. For more information, see the Paketo documentation.

Stack support

For Bionic stacks, if your app has to compile native extensions using node-gyp, you must use the full builder. This is because node-gyp requires python, which is excluded from the the base builder, and the module might require other shared objects.

For Jammy stacks, neither full stack nor base stack contains Python. For apps that require Python, you must use the Python buildpack as a supply buildpack.

Supported Service Bindings

You can configure the Node.js buildpack using service bindings.

type Required Files # Bindings of This Type Accepted
npmrc type, .npmrc 0 or 1
yarnrc type, .yarnrc 0 or 1

Apps that use NPM

If your app uses NPM, you can add the .npmrc file at either project-level or user-level.

  • Project-level .npmrc:

    Adding an .npmrc file in your app's working directory allows you to provide project-level npm configuration.

  • Global .npmrc:

    You might prefer not to include an .npmrc file in your source code and app image, for example, if an .npmrc contains credentials for connecting to a private registry. You can provide the .npmrc by using a service binding of type npmrc. The binding must contain a file called .npmrc. The Node.js buildpack sets this binding as the [NPM_CONFIG_GLOBALCONFIG][npmrc/precedence] in the build environment.

    To run pack build with the binding:

    pack build myapp  --env SERVICE_BINDING_ROOT=/bindings --volume <absolute-path-to-binding-dir>:/bindings/npmrc

Apps that use Yarn

If your app uses Yarn, you can add the .yarnrc file at either project-level or user-level.

  • Project-level .yarnrc:

    Adding an .yarnrc file in your app's working directory allows you to provide project-level yarn configuration.

  • User-level .yarnrc:

    You might prefer not to include an .yarnrc file in your source code and app image. You can provide the .yarnrc by using a service binding of type yarnrc. The binding must contain a file called .yarnrc. The Node.js buildpack sets this binding at the user-level .yarnrc in the build environment. It will not be present in the launch environment.

    To run pack build with the binding:

    pack build myapp --env SERVICE_BINDING_ROOT=/bindings --volume <absolute-path-to-binding-dir>:/bindings/yarnrc

Additional Configuration

Use the instructions in the following sections for additional features you can configure for your application.

Install a Custom CA Certificate

You can provide your own CA certificates and have them included within the container root truststore at build-time and runtime by following the instructions in CA Certificates.

Override the Start Process Set by the Buildpack

You can set custom start processes for their app image by following the instructions in the Tanzu Procfile Buildpack.

Set Environment Variables for App Launch Time

You can embed launch-time environment variables in your app image by following the instructions in Environment Variables.

Add Custom Labels to the App Image

You can can add labels to your app image by following the instructions in the Applying Custom Labels.

Example App build

The following sections demonstrate building the Paketo NPM samples app on different platforms.

Tanzu Application Platform

For an example NPM app that can be built by the Node.js buildpack, see the Paketo samples repository.

To build an app using Tanzu Application Platform:

  1. Create a workload.yaml.

    ---
apiVersion: carto.run/v1alpha1
kind: Workload
metadata:
  labels:
    app.kubernetes.io/part-of: npm-sample
    apps.tanzu.vmware.com/has-tests: "true"
    apps.tanzu.vmware.com/workload-type: web
  name: npm-sample
spec:
  params:
  - name: ports
    value:
    - port: 80
      containerPort: 8000
      name: http
  source:
    git:
      ref:
        branch: main
      url: https://github.com/paketo-buildpacks/samples
    subPath: nodejs/npm

    Where metadata.name is the application name the workload is a part of, and spec.source.git points to the remote source code.

  2. Trigger an image build in the my-apps namespace by running:

    tanzu apps workload apply --file workload.yaml --namespace my-apps

  3. After the build completes, you can view the result by running:

    tanzu apps workload get npm-sample --namespace my-apps

Tanzu Build Service

The Node.js buildpack is available in both the full and lite descriptors for Tanzu Build Service. Use kp image create to create an image resource. For more information, see the Tanzu Build Service documentation

Pack

For instructions for how to build the sample app using pack, see the paketo-buildpacks README in GitHub.

Buildpack-Set Environment Variables

The Node.js buildpack sets a number of environment variables during the build and launch phases of the app life cycle. The following sections 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 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 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