Permalink
Fetching contributors…
Cannot retrieve contributors at this time
159 lines (105 sloc) 7.25 KB
---
title: Node.js Buildpack
owner: Buildpacks
---
<strong><%= modified_date %></strong>
Use the Node.js buildpack with Node or JavaScript apps.
You must install the [Cloud Foundry Command Line Interface tool](../../cf-cli/install-go-cli.html) (cf CLI) to run some of the commands listed in this topic.
## <a id='pushing_apps'></a>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 `cf push APP-NAME -b https://github.com/cloudfoundry/nodejs-buildpack`, where `APP-NAME` is the name of your app, to push your app with the latest version of the buildpack.
For example:
<pre class='terminal'>
$ cf push my-nodejs-app -b https://github.com/cloudfoundry/nodejs-buildpack
</pre>
For more detailed information about deploying Node.js apps, see the following topics:
* <a href="./node-tips.html" class="subnav">Tips for Node.js Developers</a>
* <a href="./node-environment.html" class="subnav">Environment Variables Defined by the Node Buildpack</a>
* <a href="./node-service-bindings.html" class="subnav">Configuring Service Connections for Node</a>
* <a href="https://github.com/cloudfoundry/nodejs-buildpack">Node.js Buildpack Source Code on GitHub</a>
## <a id='supported_versions'></a>Supported Versions ##
For a list of supported Node versions, see the Node.js Buildpack [release notes](https://github.com/cloudfoundry/nodejs-buildpack/releases) on GitHub.
## <a id='runtime'></a>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:
<pre class='terminal'>
Could not get translated url, exited with: DEPENDENCY_MISSING_IN_MANIFEST:...
!
! exit
!
Staging failed: Buildpack compilation step failed
</pre>
## <a id='npm_version'></a>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](https://nodejs.org/en/download/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:
<pre class='terminal'>
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
</pre>
## <a id='vendoring'></a>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:
<pre class="terminal">
$ cd my-nodejs-app
$ npm install
</pre>
The `cf push` command uploads the vendored dependencies with the app.
<p class='note'><strong>Note</strong>: For an app to run in a disconnected environment, it must vendor its dependencies.
For more information, see <a href="https://github.com/cf-buildpacks/buildpack-packager/blob/master/doc/disconnected_environments.md">Disconnected environments</a>.</p>
### <a id='yarn_disconnected'></a>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](https://yarnpkg.com/) in a disconnected environment. To do so, you must mirror the Yarn registry locally:
<pre class="terminal">
$ 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
</pre>
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](https://yarnpkg.com/blog/2016/11/24/offline-mirror).
### <a id='integrity-check'></a>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](http://cwe.mitre.org/data/definitions/494.html).
If missing dependencies are detected, the buildpack runs `npm install` for non-vendored dependencies or `npm rebuild` for dependencies that are already vendored. This may result in code being downloaded and executed without verification.
You can use Yarn as an alternative that verifies dependencies.
## <a id='openssl'></a>OpenSSL Support ##
The [nodejs-buildpack](https://github.com/cloudfoundry/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](https://github.com/cloudfoundry/binary-builder) enables [ static OpenSSL compilation](https://github.com/cloudfoundry/binary-builder/commit/834759affa4d7e42294a54b49bac6f1cf81b798a).
## <a id='proxy_support'></a> 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](http://docs.cloudfoundry.org/buildpacks/proxy-usage.html) topic.
## <a id='bosh_trusted_cert'></a>BOSH Configured Custom Trusted Certificate Support ##
Node.js hardcodes root CA certs in its source code. To use [BOSH configured custom trusted certificates](http://bosh.io/docs/trusted-certs.html), a developer must pass the specified CAs to the [tls.connect](https://nodejs.org/api/tls.html#tls_tls_connect_port_host_options_callback) function as extra arguments.
## <a id='help_support'></a>Help and Support ##
Join the #buildpacks channel in our [Slack community] (http://slack.cloudfoundry.org/) 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](https://github.com/cloudfoundry/nodejs-buildpack).
You can find current information about this buildpack in the Node.js buildpack
[release page](https://github.com/cloudfoundry/nodejs-buildpack/releases) in GitHub.