Node.js Buildpack

Page last updated:

Use the Node.js buildpack with Node or JavaScript apps.

You need to install the Cloud Foundry Command Line Interface (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 CLI cf push command push. If your Cloud Foundry deployment does not have the Node.js buildpack installed or the installed version is out of date, run cf push APP-NAME -b https://github.com/cloudfoundry/nodejs-buildpack and replace APP-NAME with the name of your app to push your app with the latest version of the buildpack.

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

Vendor App Dependencies

To vendor dependencies for an app using the Node.js buildpack, run npm install 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.

Note: For an app to run in a disconnected environment, it must vendor its dependencies. For more information, see Disconnected environments.

Using Yarn in a Disconnected Environment

Versions 1.5.28 and later of the Node.js buildpack include the ability to use the package manager Yarn in a disconnected environment. To do so, you must mirror the Yarn registry locally:

$ cd APP-DIR
$ yarn config set yarn-offline-mirror ./npm-packages-offline-cache
$ 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 requires an Internet connection.

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

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 the Proxy Usage topic.

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