heroku dev center

Heroku Node.js Support

Last Updated: 31 March 2014

cedar node

Table of Contents

This document describes the general behavior of the Cedar stack 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.

If you have questions about Node.js on Heroku, consider discussing it in the Node.js on Heroku forums.

Activation

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

Versions

Heroku allows you to run any version of Node.js greater than 0.8.5, including unstable pre-release versions like 0.11.8. Use the engines section of your package.json to specify the version of Node.js to use on Heroku.

To see what versions of node are currently available, visit semver.io/node.json or what-is-the-latest-version-of-node.com.

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

You should always specify a node version, but if you don’t the latest stable version will be used. There is no need to specify an npm version, as npm is bundled with node.

Environment

The following environment variables will be set:

PATH=vendor/node/bin:bin:node_modules/.bin:$PATH
NODE_ENV=production

The NODE_ENV environment variable defaults to production, but you can override it if you wish:

heroku config:set NODE_ENV=staging

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

If you add node_modules to your .gitignore file, the build cache is used. If you check your node_modules directory into source control, the build cache is not used.

npm install --production 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, else they will be removed by npm prune.

On each build, the node runtime version is checked against the version in the previous build. If the version has changed, npm rebuild is run automatically to recompile any binary dependencies. This ensures your app’s dependencies are compatible with the installed node version.

Customizing the Build Process

If your app has a build step that you’d like to run when you deploy, you can use an npm postinstall script, which will be executed automatically after the buildpack runs npm install --production. Here’s an example:

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

Your app’s environment is available during the build, allowing you to adjust build behavior based on the values of environment variables such as NODE_ENV.

By default, the Heroku node buildpack runs npm install --production, which doesn’t install devDependencies in your package.json file. If you wish to install development dependencies when deploying to Heroku, there are two ways to do so:

  • Move your build dependencies (such as grunt plugins) from devDependencies to dependencies in package.json.
  • Configure npm to install all dependencies by setting a config var:
$ heroku config:set npm_config_production=false

Runtime Behavior

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

$ cat Procfile
web: npm start

Default Web Process Type

A Procfile is not required to run a Node.js app on Heroku. If no Procfile is present in the root directory of your app during the build process, we will check for a scripts.start entry in your package.json file. If a start script entry is present, a default Procfile is generated automatically:

$ cat Procfile
web: npm start

Read more about npm script behavior at npmjs.org.

Add-ons

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

$ heroku addons:add heroku-postgresql

Going further

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