Deploying Node.js Apps on Heroku
Last updated September 04, 2025
Table of Contents
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:
- Node.js and npm installed.
- An existing Node.js app.
- A free Heroku account.
- The Heroku CLI.
Overview
Heroku Node.js application detection only applies when an app has a package.json
file in the root directory.
See Node.js Behavior in Heroku 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.
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
...
package name: (node-example)
version: (1.0.0)
description: This example is so cool.
git repository:
author: jane-doe
license: (ISC) MIT
...
The generated package.json
file should look similar to the following:
{
"name": "node-example",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "jane-doe",
"license": "MIT",
"description": "This example is so cool."
}
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
.
This can be done by specifying the engines.node
field in package.json
like this:
"engines": {
"node": "22.x"
},
See Specifying a Node.js Version for more info.
With the dependencies installed and the Node.js version specified, the package.json
file should look like:
{
"name": "node-example",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "jane-doe",
"license": "MIT",
"description": "This example is so cool.",
"dependencies": {
"express": "^5.1.0"
},
"engines": {
"node": "22.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 Node.js Behavior in Heroku.
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
- Read Best Practices for Node.js Development.
- To learn more about developing and deploying Node.js applications, visit the Node.js category.