Last updated May 20, 2021

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. Heroku will support new releases within 24 hours of the official release from the Node team.

Currently, supported versions are 12.x, 14.x, and 16.x.

Other available runtimes

Since Heroku is based on a standard Ubuntu Linux stack, you can run most Node versions (>= 0.10.0) 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
v14.15.4

First, ensure that your application is using the heroku/nodejs buildpack:

$ heroku buildpacks
=== issuetriage Buildpack URLs
1. heroku/nodejs

Now, use the engines section of the 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": "14.x"
  }
}

It’s recommended to use an x in the patch to get the latest patch updates from Node. A minor range (eg, 14.15) and an exact version (eg, 14.15.4) can be specified too.

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 version 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": "6.x"
  }
}

Specifying a Yarn Version

If a yarn.lock file is found at the root of your application along with package.json, Heroku will download and install Yarn and use it to install your dependencies. However, you should specify which version you are using locally so that same version can be used on Heroku.

{
  "name": "myapp",
  "description": "a really cool app",
  "version": "1.0.0",
  "engines": {
    "yarn": "1.x"
  }
}

Build behavior

Node projects are built with either the Yarn package manager or with the npm package manager.

If a yarn.lock file is detected in the root of the project, yarn is used for installing dependencies and running scripts. Otherwise, npm is used. If you have yarn.lock checked into your project, but still want to use npm to build on Heroku, just add yarn.lock to your .slugignore file.

Package Installation

By default, Heroku will install all dependencies listed in package.json under dependencies and devDependencies.

After running the installation and build steps Heroku will strip out the packages declared under devDependencies before deploying the application.

Heroku uses the lockfiles, either the package-lock.json or yarn.lock, to install the expected dependency tree, so be sure to check those files into git to ensure the same dependency versions across environments. If you are using npm, Heroku will use npm ci to set up the build environment.

Using npm install

If you’d rather use npm install instead of npm ci to create the build environment, you can use the USE_NPM_INSTALL environment variable to let the buildpack know. You can do this by running:

$ heroku config:set USE_NPM_INSTALL=true

If you use npm install, you will want to use your Heroku cache to speed up your build times. If you’re not using npm install, you can go ahead and disable the build cache.

$ heroku config:set NODE_MODULES_CACHE=false

Only installing dependencies

You can direct Heroku to only install dependencies by setting environment variables NPM_CONFIG_PRODUCTION=true or YARN_PRODUCTION=true.

$ heroku config:set NPM_CONFIG_PRODUCTION=true YARN_PRODUCTION=true

Skip pruning

If you need access to packages declared under devDependencies in a different buildpack or at runtime, then you can set NPM_CONFIG_PRODUCTION=false or YARN_PRODUCTION=false to skip the pruning step.

$ heroku config:set NPM_CONFIG_PRODUCTION=false YARN_PRODUCTION=false

NODE_ENV is not production

By default NODE_ENV is set to production. If NODE_ENV is any other value, the pruning step will be skipped.

$ git push heroku main
...
-----> Pruning devDependencies
       Skipping because NODE_ENV is 'test'
...

Pruning devDependencies with Yarn 2

The Yarn 2 package manager is modularized, so you’ll have to install the workspaces plugin in order to prune out devDependencies. This is suggested because the Node.js runtime will not need devDependencies installed, so it’s preferred to remove them after the build is complete so that they are not compiled into the slug.

In order to install, run the following:

$ yarn plugin import workspaces-tools

Check in all the created artifacts into git with the other files that have been generated to use Yarn in the .yarn file.

Customizing the build process

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

"scripts": {
  "start": "node index.js",
  "build": "webpack"
}

If the package.json has a build script that needs to be customized for Heroku, define a heroku-postbuild script, which will run instead of the build script.

"scripts": {
  "start": "node index.js",
  "build": "ng build",
  "heroku-postbuild": "ng build --prod" // this will be run on Heroku
}

Heroku-specific build steps

While npm install and yarn install have standard preinstall and postinstall scripts, you may want to run scripts only before or after other Heroku build steps. 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, heroku-postbuild, and heroku-cleanup scripts:

"scripts": {
  "heroku-prebuild": "echo This runs before Heroku installs dependencies.",
  "heroku-postbuild": "echo This runs after Heroku installs dependencies, but before Heroku prunes and caches dependencies.",
  "heroku-cleanup": "echo This runs after Heroku prunes and caches dependencies."
}

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

Build flags

If your app is running a build step, make sure that it is used for development and production. If it’s not, then use the build flag environment variable to set flags for the build script. For instance, if your build step is:

"scripts": {
  "build": "ng build"
}

You can set the NODE_BUILD_FLAGS environment variable:

$ heroku config:set NODE_BUILD_FLAGS="--prod"

Setting this variable will run ng build --prod in the build step instead.

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.

Private Dependencies

If pulling from a private dependency source, such as NPM Enterprise or Gemfury, the project will need to configure an alternate registry with access tokens.

Add the private registry url to the .npmrc. In this case, we’ll specify npm‘s registry even though its public. The scope should be replaced with the scope that is used for the private module in the registry. Then, add the registry url that will point to using the auth token.

echo "@scope:registry=https://registry.npmjs.org" >> .npmrc
echo -e "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" >> .npmrc

The .npmrc should look like this:

@scope:registry=https://registry.npmjs.org
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Make sure the NPM_TOKEN has been added to the Heroku config, so that the build can access the token and install the private package.

heroku config:set NPM_TOKEN=PRIVATE_NPM_TOKEN

Customize Binary Downloads

You can customize where Node and yarn binaries are downloaded by setting environment variables NODE_BINARY_URL and YARN_BINARY_URL to a custom URL. For instance:

$ heroku config:set NODE_BINARY_URL=https://s3.amazonaws.com/your-custom-binary-url/

Cache behavior

Heroku maintains a build cache that is persisted between builds. This cache is used to store caches for npm, yarn, and bower.

You can disable all caching for Node.js apps if you prefer:

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

Custom caching

Heroku stores the node_modules and bower_components directories by default. You can override these defaults by providing a cacheDirectories array in your top-level package.json.

For example, if you build inside client and server sub-directories:

"cacheDirectories": ["client/node_modules", "server/node_modules"]

Or perhaps your app needs a large dictionary of some sort, stored in data/dictionary.txt:

"cacheDirectories": ["data"]

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"
}

If you only want to run non-web processes in your app’s formation, you’ll need to explicitly scale web down and the other process types up. For example:

$ heroku scale web=0 worker=1

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.