Heroku Node.js Support

Last updated 19 September 2016

This document describes the general behavior of Heroku as it relates to the recognition and execution of Node.js applications. For a more detailed explanation of how to deploy an application, see Getting Started with Node.js on Heroku.

Activation

The Heroku Node.js buildpack is employed when the application has a package.json file in the root directory.

Node.js runtimes

Node versions adhere to semver, the semantic versioning convention popularized by GitHub. Semver uses a version scheme in the form MAJOR.MINOR.PATCH.

• MAJOR denotes incompatible API changes
• MINOR denotes added functionality in a backwards-compatible manner
• PATCH denotes backwards-compatible bug fixes

Supported runtimes

Heroku supports the latest Stable version of Node.js as well as all active LTS (Long-Term-Support) versions.

Currently supported versions are 4.x and 6.x. If you’re still on node 0.10 or 0.12, you should begin updating as those will soon be unmaintained. If you’re on 5.x, you should have an easy transition to 6.x as it’s just a continuation of that branch.

Other available runtimes

Since Heroku is based on a standard Ubuntu Linux stack, you can run most node versions (>= 0.8.6) on the platform. However, the testing and support focus of the buildpack will be oriented around active LTS and Stable releases.

Specifying a Node.js Version

You should always specify a Node.js version that matches the runtime you’re developing and testing with. To find your version locally:

$ node --version
v4.1.1

Use the engines section of your package.json to specify the version of Node.js to use on Heroku. Drop the ‘v’ to save only the version number:

{
  "name": "myapp",
  "description": "a really cool app",
  "version": "1.0.0",
  "engines": {
    "node": "4.1.1"
  }
}

You can also specify a semver range (4.x). This is not recommended in production, where runtime versions should not float.

Specifying an Npm Version

Node.js comes bundled with npm, so most of the time you don’t need to specify a separate npm version. However, if you intentionally use a different of npm locally, you can specify the same version of npm on Heroku:

{
  "name": "myapp",
  "description": "a really cool app",
  "version": "0.0.1",
  "engines": {
    "npm": "2.1.x"
  }
}

Build behavior

npm install is run on every build, even if the node_modules directory is already present, to ensure execution of any npm script hooks defined in your package.json.

npm prune is run after restoring cached modules to ensure cleanup of any unused dependencies. You must specify all of your application’s dependencies in package.json, otherwise they will be removed by pruning.

Customizing the build process

If your app has a build step that you’d like to run when you deploy, you can use a postinstall script in package.json:

"scripts": {
  "start": "node index.js",
  "test": "mocha",
  "postinstall": "bower install && grunt build"
}

Heroku-specific build steps

While Node.js has standard preinstall and postinstall scripts, sometimes you may want to run scripts only before or after builds on Heroku. For instance, you may need to configure npm, git, or ssh before Heroku installs dependencies. Or, you may need to build production assets after dependencies are installed.

For Heroku-specific actions, use the heroku-prebuild and heroku-postbuild scripts:

"scripts": {
  "heroku-prebuild": "echo This runs before Heroku installs your dependencies.",
  "heroku-postbuild": "echo This runs afterwards."
}

Environment variables

Your app’s environment is available during the build, allowing you to adjust build behavior based on the values of environment variables. For instance:

$ heroku config:set MY_CUSTOM_VALUE=foobar

Configuring NPM

Npm reads configuration from any environment variables beginning with NPM_CONFIG.

You can also control npm’s behavior via a .npmrc file in your project’s root.

devDependencies

We set NPM_CONFIG_PRODUCTION to true by default to install production dependencies only. If you would like to install devDependencies, you can disable production mode:

$ heroku config:set NPM_CONFIG_PRODUCTION=false

However, since you usually don’t want all development dependencies in your production builds, it’s preferable to move only the dependencies you actually need for production builds (bower, grunt, gulp, etc) into dependencies.

Cache behavior

Heroku maintains a cache directory that is persisted between builds. This cache is used to store resolved dependencies so they don’t have to be downloaded and installed every time you deploy.

By default, NODE_MODULES_CACHE is true, but you can disable caching by setting it to false:

$ heroku config:set NODE_MODULES_CACHE=false
$ git commit -am 'disable node_modules cache' --allow-empty
$ git push heroku master

Custom caching

While we cache both node_modules and bower_components by default, some projects benefit from fine-grained control over caching. For instance, you may install bower components in another directory, or you may want to cache the dependencies of “client” and “server” sub-directories.

To override what is cached between builds, provide a cacheDirectories array in your top-level package.json:

"cacheDirectories": ["node_modules", "bower_components", "public/build" ]

Runtime behavior

The buildpack puts node, npm, and node_modules/.bin on the PATH so they can be executed with heroku run or used directly in a Procfile:

$ cat Procfile
web: npm start

The NODE_ENV environment variable is set to 'production’ by default, but you can set it to any arbitrary string:

heroku config:set NODE_ENV=staging

Default web process type

First, Heroku looks for a Procfile specifying your process types.

If no Procfile is present in the root directory of your app during the build process, your web process will be started by running npm start, a script you can specify in package.json, eg:

"scripts": {
  "start": "node server.js"
}

Read more about npm script behavior at npmjs.org.

Warnings

If a build fails, the Node.js Buildpack identifies common issues in Node applications and provides warnings with best-practice recommendations. If you’re experiencing Node.js build issues, this is a good place to start debugging.

We also maintain a document to help troubleshoot common Node.js issues.

Add-ons

No add-ons are provisioned by default. If you need a database for your app, add one explicitly:

$ heroku addons:create heroku-postgresql

Multi-buildpack behavior

When using the Node.js Buildpack with other buildpacks, it automatically exports the node, npm, and node_modules binaries onto the PATH for subsequent buildpacks to consume.

Going further

The Heroku Node.js buildpack is open source. For a better technical understanding of how the buildpack works, check out the source code at github.com/heroku/heroku-buildpack-nodejs.