Deploying Node.js Apps on Heroku

Last updated December 04, 2024

This article describes how to take an existing Node.js app and deploy it to Heroku.

If you’re new to Heroku, check out Getting Started with Node.js on Heroku.

Prerequisites

This article assumes that you have:

Overview

Heroku Node.js support is only applied when the application has a package.json file in the root directory.

See Heroku Node.js Support for more info.

Declare App Dependencies

The package.json file defines the dependencies to install with your application. To create a package.json file for your app, run the npm init command in your app’s root directory. It shows you how to create a package.json file. You can skip any of the prompts by leaving them blank.

Use the git bash application to open a command shell on Windows. The CLI installation added a shortcut for this application to your desktop.
$ cd node-example
$ npm init
...
name: (node-example)
version: (1.0.0)
description: This example is so cool.
entry point: (web.js)
test command:
git repository:
keywords: example heroku
author: jane-doe
license: (ISC) MIT
...

The generated package.json file looks like:

{
  "name": "node-example",
  "version": "1.0.0",
  "description": "This example is so cool.",
  "main": "web.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "example",
    "heroku"
  ],
  "author": "jane-doe",
  "license": "MIT"
}

To install dependencies, use npm install <package>, which also adds the package as a dependency in the package.json file. For example, to install express, type npm install express.

Make sure that you don’t rely on any system-level packages. Missing dependencies in your package.json file cause problems when you try to deploy to Heroku. To troubleshoot this issue, on your local command line, type rm -rf node_modules; npm install --production, and then try to run your app locally by typing heroku local web. If your package.json file is missing a dependency, you see an error that indicates which module can’t be found.

Specify the Node Version

Specify the Node.js version used to run your application on Heroku in your package.json file. Always specify a Node.js version that matches the runtime that you’re developing and testing with. To find your version, type node --version.

Your package.json file looks like:

"engines": {
  "node": "22.x"
},

In the Node.js versioning scheme, odd versions are unstable and even versions are stable. The stable branch takes bug fixes only.

With the dependencies installed and the node version specified, the package.json file looks like:

{
  "name": "node-example",
  "version": "1.0.0",
  "description": "This example is so cool.",
  "main": "web.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "example",
    "heroku"
  ],
  "author": "jane-doe",
  "license": "MIT",
  "dependencies": {
    "express": "^4.9.8"
  },
  "engines": {
    "node": "22.x"
  }
}

It’s a good idea to keep your development environment and production environment as similar as possible. Make sure that your local Node.js version matches the version that you told Heroku to use in the package.json file. To check which version you’re running locally, at the command line, type node --version.

Specify a Start Script

To determine how to start your app, Heroku first looks for a Procfile. If no Procfile exists for a Node.js app, we attempt to start a default web process via the start script in your package.json.

The command in a web process type must bind to the port number specified in the PORT environment variable. If it doesn’t, the dyno doesn’t start.

For more information, see Best Practices for Node.js Development and Heroku Node.js Support.

Build Your App and Run It Locally

To install the dependencies that you declared in your package.json file, run the npm install command in your local app directory.

$ npm install

Start your app locally using the heroku local command, which installed as part of the Heroku CLI.

$ heroku local web --port 5001

Your app now runs on http://localhost:5001/.

How to Keep Build Artifacts Out of Git

We don’t recommend checking node_modules into Git because it causes the build cache to not be used. For more information, see build behavior.

Prevent build artifacts from going into revision control by creating a .gitignore file that looks like:

/node_modules
npm-debug.log
.DS_Store
/*.env

Deploy Your Application to Heroku

After you commit your changes to Git, you can deploy your app to Heroku.

$ git add .
$ git commit -m "Added a Procfile."
$ heroku login
Enter your Heroku credentials.
...
$ heroku create example-app
Creating example-app... done, stack is cedar
http://example-app-1234567890ab.herokuapp.com/ | git@heroku.com:arcane-lowlands-8408.git
Git remote heroku added
$ git push heroku main
...
-----> Node.js app detected
...
-----> Launching... done
       http://example-app-1234567890ab.herokuapp.com deployed to Heroku

To open the app in your browser, type heroku open.

Provision a Database

The add-on marketplace has a large number of data stores, such as Postgres, Redis, MongoDB, and MySQL.

Next Steps

Feedback

Log in to submit feedback.