Last updated October 31, 2023

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

Prerequisites

This article assumes that you have:

• Node.js and npm installed.
• An existing Node.js app.
• A free Heroku account.
• The Heroku CLI.

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.

$ 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": "20.x"
},

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

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

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.

Advanced HTTP Features

The HTTP stack available to Common Runtime apps on the herokuapp.com subdomain supports HTTP 1.1, long polling, chunked responses, and WebSockets.

Provision a Database

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

Next Steps

• Read Best Practices for Node.js Development.
• To learn more about developing and deploying Node.js applications, visit the Node.js category.