Node.js buildpack

Page last updated:

You can configure and use the Node.js buildpack in Cloud Foundry.

You can use the Node.js buildpack with Node or JavaScript apps. The follow sections describe how to push apps with the Node.js buildpack, along with features of the buildpack.

You must install the Cloud Foundry Command Line Interface tool (cf CLI) to run some of the commands listed in this topic.

Push Node.js apps

Cloud Foundry automatically uses the Node.js buildpack if it detects a package.json file in the root directory of your project.

The -b option lets you specify a buildpack to use with the cf push command. If your Cloud Foundry deployment does not have the Node.js buildpack installed or the installed version is out of date, run the following command to push your app with the latest version of the buildpack:

cf push APP-NAME -b https://github.com/cloudfoundry/nodejs-buildpack

Where APP-NAME is the name of your app.

For example: 

$ cf push my-nodejs-app -b https://github.com/cloudfoundry/nodejs-buildpack

For more detailed information about deploying Node.js apps, see the following topics:

Supported versions

For a list of supported Node versions, see the Node.js Buildpack release notes on GitHub.

Specify a Node.js version

To specify a Node.js version, set the engines.node in the package.json file to the semantic versioning specification (semver) range or the specific version of Node you are using.

Example showing a semver range:

"engines": {
  "node": "6.9.x"
}

Example showing a specific version:

"engines": {
  "node": "6.9.0"
}

If you try to use a version that is not currently supported, staging your app fails with the following error message:

Could not get translated url, exited with: DEPENDENCY_MISSING_IN_MANIFEST:...
!
!     exit
!
Staging failed: Buildpack compilation step failed

Specify an npm version

To specify an npm version, set engines.npm in the package.json file to the semantic versioning specification (semver) range or the specific version of npm you are using:

Example showing a semver range:

"engines": {
  "node": "6.9.x",
  "npm": "2.15.x"
}

Example showing a specific version:

"engines": {
  "node": "6.9.0",
  "npm": "2.15.1"
}

If you do not specify an npm version, your app uses the default npm packaged with the Node.js version used by your app, as specified on the Node.js releases page.

If your environment cannot connect to the Internet and you specified a non-supported version of npm, the buildpack fails to download npm and you see the following error message:

We're unable to download the version of npm you've provided (...).
Please remove the npm version specification in package.json (...)
Staging failed: Buildpack compilation step failed

Using npm or Yarn

By default, the Node.js buildpack assumes you are using npm. If you want to use Yarn instead, you must provide a yarn.lock in your top-level app directory. For more information on the Yarn lock file, see yarn.lock in the Yarn documentation.

Vendoring app dependencies

To vendor dependencies for an app using the Node.js buildpack, run npm install (or yarn install, if you are using Yarn) from your app directory. This command vendors dependencies into the node_modules directory of your app directory.

For example, the following example vendors dependencies into the my-nodejs-app/node_modules directory:

$ cd my-nodejs-app
$ npm install

The cf push command uploads the vendored dependencies with the app.

For an app to run in a disconnected environment, it must vendor its dependencies and provide a lock file.

Use in offline environments

When vendoring apps for usage in offline environments, you must supply a lock file. For information on npm lockfiles, see npm-package-locks in the NPM documentation.

For information on npm-package-lock.json files, see package-lock.json in the NPM documentation.

This lock file informs the package manager of the exact versions of dependencies and transitive dependencies to look for when running npm install or yarn install. For this reason, you must keep package.json, the vendored node_modules directory, and your lock file synchronized to avoid network calls.

The package-lock.json file is only supported by NPM 5.x and later. For earlier versions of NPM, provide a npm-shrinkwrap.json file instead.

Versions 1.5.28 and later of the Node.js buildpack include the ability to use Yarn in offline mode. To do so, you must mirror the Yarn registry locally by providing an npm-packages-offline-cache directory:

$ cd APP-DIR
$ yarn config set yarn-offline-mirror ./npm-packages-offline-cache
$ yarn config set yarn-offline-mirror-pruning true
$ cp ~/.yarnrc .
$ rm -rf node_modules/ yarn.lock # if they were previously generated
$ yarn install

When you push the app, the buildpack looks for an npm-packages-offline-cache directory at the top level of the app directory. If this directory exists, the buildpack runs Yarn in offline mode. Otherwise, it runs Yarn normally, which may require an Internet connection. You do not have to provide a node_modules directory when running Yarn in offline mode, as the offline cache provides the dependencies.

For more information about using an offline mirror with Yarn, see the Yarn Blog.

Integrity check

By default, the Node.js buildpack uses npm to download dependencies. Note, that npm does not perform integrity checks of the downloaded packages, which is a security risk.

If missing dependencies are detected, the buildpack runs npm install for non-vendored dependencies or npm rebuild for dependencies that are already vendored. This might result in code being downloaded and run without verification.

You can use Yarn as an alternative that verifies dependencies.

OpenSSL support

The nodejs-buildpack packages binaries of Node.js with OpenSSL that are statically linked. The Node.js buildpack supports Node.js 4.x and later, which relies on the Node.js release cycle to provide OpenSSL updates. The binary-builder enables static OpenSSL compilation.

Proxy support

If you need to use a proxy to download dependencies during staging, you can set the http_proxy and/or https_proxy environment variables. For more information, see Using a Proxy.

BOSH configured custom trusted certificate support

Node.js hardcodes root CA certs in its source code. To use BOSH configured custom trusted certificates, a developer must pass the specified CAs to the tls.connect function as extra arguments.

Help and support

Join the #buildpacks channel in our Slack community if you need any further assistance.

For more information about using and extending the Node.js buildpack in Cloud Foundry, see the Node.js GitHub repository.

You can find current information about this buildpack in the Node.js buildpack release page in GitHub.

Create a pull request or raise an issue on the source for this page in GitHub