Deploying to Heroku can feel overwhelmingly confusing. But it doesn't have to be.

In this short article, we'll take a look at how we can deploy a bare-bones Express server to Heroku. For our initial setup, feel free to clone the following Github repo and run npm install to install all file dependencies.

IF you decide to clone the above, please continue to Step 4

( Don't forget to run npm install )!

However, if you'd like to build from scratch, let's start up a project folder with the following setup:

1. A package.json folder (type npm init into your terminal and accept all defaults to generate this file)
2. Replace the value at key "main:" inside your package.json with the following: "main": "index.js", (see section 2 for full example)
3. Express installed (type npm i express to install Express)
4. A file called index.js in your root project directory, with section 1 example code
5. Install git if you haven't already

1. Dynamic Port Binding

Whenever we deploy our app to Heroku, Heroku will tell us which port we'll have to listen to.

Let's look at a basic Express server setup, where we've hard-coded the port number:

// index.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send({hi: 'there'});
});

app.listen(5001);

After we deploy our app, Heroku has the ability to inject environmental variables. These variables allow Heroku to pass our server variables after we've launched our app to Heroku's server. Note that we can't know what these variables are ahead of time.

// index.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send({hi: 'there'});
});

// Gives Heroku the ability to assign our app a port
const PORT = process.env.PORT || 5001;

app.listen(PORT);

With the addition of our PORT variable passed as an argument to app.listen, we're stating that if our PORT has a value (from Heroku), use that value. Else, use port 5001.

2. Specifying Node's Version

By default, Heroku attempts to use an older version of Node. That said, you can tell Heroku to use a specific version (i.e. the version you're likely using while building your app).

We can accomplish this by adding a engines property in our package.json file:

// package.json
{
  "name": "server",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "engines": {
    "node": "8.8.1",
    "npm": "5.0.3"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.17.2"
  }
}

Done! Now Heroku knows to use Node version 8.8.1 and npm version 5.0.3.

Specifying a Start Script

When we deploy to Heroku, we'll have to tell it which command we'd like it to run to start up our server.

What we'll do here is tell Heroku how we'll start up our server. Back in our package.json, we'll replace our previous test script with the following:

// package.json
{
  "name": "server",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "engines": {
    "node": "8.8.1",
    "npm": "5.0.3"
  },
  "scripts": {
    "start": "node index.js"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.17.2"
  }
}

Now, when we deploy our app, Heroku will run our start script, which Heroku will execute on our behalf.

Create a .gitignore File

We don't want to upload everything to Heroku, such as our node_modules files, since Heroku will install those node_modules for us.

Inside the root directory of your project, add a file called .gitignore. Inside it, enter in node_modules. Now when we commit our file, Heroku (and other services) will ignore our node_modules folder, along with any other folder path or file name we add to .gitignore.

Let's Deploy to Heroku

Here is the process we'll follow to deploy our app to Heroku:

Step 1 - Create Heroku account here

Step 2 - Commit our codebase to git In a terminal of your root directory. Type git init

After, type git add .

Lastly, type git commit -m "initial commit"

Note that we should not see node_modules in this initial commit. Step 3 - Install Heroku's CLI here

After Heroku's CLI has successfully installed, you should be able to see Heroku's version in the terminal of your app's root directory by typing in heroku -v.

Next, type heroku login in the terminal and follow the prompts to login.

Step 4 - Deploy app

Afterwards, type heroku create. We should see some output that contains two separate links:

The first link is a URL we can visit to see our app on the web. The second link is the one we should focus on. This second link is our git repository that we can push our local server to. Copy the second link and type the following:

git remote add heroku <<paste your second link here>>

This adds a remote repository to our current repository. We can validate this by typing git remote --v. We should see output that corresponds with the second link that Heroku gave us.

Step 5 - Deploy!

All that's let to do is type the following command:

git push heroku master

The instant we push our code into this repository, Heroku will start to launch your app online. Pretty cool!

If all goes well, we should see Verifying deploy... done. as well as a URL that Heroku gives us in its final line.

And finally... type heroku open. This should take us to our browser, where we see our mighty Express server running in the wild:

HOW COOL! We've successfully deployed our server to the web.

If you see errors! Go back to the terminal and run heroku logs. This will take you to an error log, which might give you hints on any snags you may have hit.

Handling re-deployments

But what if we want our express server to do more than reply with "hi": "there"? Thankfully, making edits and re-deploying our app to Heroku is simple.

Go ahead and change our message. Make a new git commit, ensuring that all files are saved. After we commit, run git push heroku master.

If we don't hit any errors, we should have successfully redeployed our app with changes made.

If you've made it this far, I hope the above has demystified deploying a simple Express server to Heroku. Best of luck and happy hacking!