Node.js Behavior in Heroku
Last updated March 17, 2025
Table of Contents
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 on Heroku with Node.js or Getting Started on Heroku Fir with Node.js.
Auto-Detection
The Node.js buildpack is used when the application has a package.json file in the root directory. For Cedar-generation apps, the Heroku classic Node.js buildpack is used, while in Fir-generation apps, the Heroku Node.js Cloud Native Buildpack is used.
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 but there is a start script in your app’s package.json then that will be used as the default web process. For example:
"scripts": {
"start": "node server.js"
}
If you only want to run non-web processes in your app’s formation, explicitly scale web down and the other process types up. For example:
$ heroku scale web=0 worker=1
Build Behavior
Heroku’s Node.js buildpacks have different build behavior depending on whether an app uses classic or Cloud Native Buildpacks (CNB). See the following articles to learn about Node.js builds and how to customize them:
Add-On Provisioning
No add-ons are provisioned by default. If you need a database for your app, add one explicitly.
$ heroku addons:create heroku-postgresql --app example-app
Multi-Buildpack Behavior
When using the Node.js buildpack with other buildpacks, it automatically exports the node binary as well the binaries for the package manager used (npm, pnpm, or yarn) onto the PATH for subsequent buildpacks to consume. The classic buildpack will also add node_modules/.bin onto the PATH.
Runtime Behavior
The buildpack exports the node binary as well the binaries for the package manager used (npm, pnpm, or yarn) onto the PATH at runtime so that you can execute with heroku run or use them directly in a Procfile. The classic buildpack will also add node_modules/.bin onto the PATH.
$ 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
Usually, you want NODE_ENV to be ‘production.’ Several modules, including express, implicitly change their behavior based on NODE_ENV.