Heroku, oh, Heroku. You used to have a free tier and help developers quickly deploy their weekend projects for free. What happened to our bond?

Although Heroku no longer has a completely free tier, it still has one of the simplest and most straightforward processes for deploying a Nest.js (Node.js) application.

In this article, I will walk you through the process of deploying a Nest.js application on Heroku, including setting up environment variables and how you can deploy other branches aside from the main branch. For the curious minds, I will also give a brief explanation of how Heroku deployment works for Node.js apps in general. Let’s get started.

Step 0: Installing the Heroku CLI Link to heading

Before we can deploy to Heroku, you need to have a Heroku account and also install the Heroku CLI application.

On Mac, you can quickly install the CLI application by running:

brew install heroku/brew/heroku

Installation instructions for other platforms are available here.

Step 1: Setting up a Nest.js application Link to heading

If you don’t already have a Nest application to deploy, you can create one by first installing the Nest CLI:

npm install -g @nestjs/cli

Then create a new application and enter the app folder:

nest new the-best-app

cd the-best-app

You can also run the app locally to confirm it starts properly:

npm run start:dev

If you are completely new to Nest.js, you can check out my Nest.js series.

Step 2: Setting the Node.js version Link to heading

Heroku requires that you specify the Node.js engine version for your project in the package.json file. You can do that by adding the engines configuration to package.json and specifying a Node.js version:

{
  "name": "the-best-app",
  "scripts": {
    ... 
  },
  "engines": {
    "node": "23.x"
  }
}

The value 23.x specifies that a Node.js engine version starting from 23. is required to start the application. E.g versions 23.1, 23.3 etc.

Step 3: Creating a Procfile Link to heading

Heroku requires that you create a file named Procfile in the root of your project (the same place the package.json file is). Note that the file should be named Procfile without any file extensions at all.

Since Nest.js already configures some scripts for starting the project inside the package.json, the content of the Procfile should be the following:

web: npm run start:prod

This tells Heroku how to start the web server: by running the start:prod script.

Verify that your package.json file contains the start:prod script, if it doesn’t, add it:

"scripts": {
  "start": "nest start",
  "start:dev": "nest start --watch",
  "start:prod": "node dist/main.js",
  "build": "nest build"
}

Step 4: Setup Git Link to heading

Heroku’s deployment process makes use of Git to enable seamless deployment. You need to initialize a git repository and commit the changes.

git init
git add .
git commit -m "Initial commit"

Step 5: Login to Heroku and Create an App Link to heading

Now that the repository is set up, we need to log in to Heroku via the Heroku CLI application we installed in step 0:

heroku login

After following the prompt to log in, create a new app on Heroku by running the following:

heroku create the-best-app

Step 6: Deploying to Heroku Link to heading

After creating an application on Heroku, to deploy, run the following command:

git push heroku main

Note that main is the default branch Heroku is configured to deploy from.

If you want to deploy another branch other than main, say feature-branch, you run:

git push heroku feature-branch:main

Step 7: Setting environment variables Link to heading

Heroku calls environment variables “config variables”. You can set them on the CLI by running:

heroku config:set PORT=3000

This sets the environment variable PORT to the value 3000.

You can also log in to the Heroku dashboard and navigate to the Settings tab:

alt text

And then scroll down to the Config Vars section to reveal the current variables and also add more: alt text

Step 8: Opening the Application and Checking Logs Link to heading

Your new application can be accessed via the Heroku dashboard or you can run the following command from the root folder:

heroku apps:open

You can also check logs on the dashboard or by running:

heroku logs --tail

How Does Heroku Deployment Work? Link to heading

When an application is created on Heroku (say by running heroku create the-best-app), Heroku creates and links a new Git remote (repository) to the app. To verify this, run:

git remote -v

You will get an output like:

heroku  https://git.heroku.com/the-best-app.git (fetch)
heroku  https://git.heroku.com/the-best-app.git (push)

origin  https://github.com/Olusamimaths/the-best-app.git (fetch)
origin  https://github.com/Olusamimaths/the-best-app.git (push)

How Heroku deployment works

You can see the heroku Git remote. This heroku remote deploys the code pushed to its main branch.

As a result, when we run git push heroku main, we are pushing the current main branch to Heroku’s main branch. It’s a shortcut for git push heroku main:main.

That means to deploy a feature branch on Heroku, we do git push heroku branch-name:main - this means we are pushing that feature branch onto Heroku’s main branch.

Conclusion Link to heading

In this article, I showed how easy it is to deploy a Nest.js application to Heroku and explained how Heroku deployment works briefly. If you enjoyed this article, then you might enjoy my other posts.