Node.js on Heroku: A More Complete Tutorial: Part 1

While Heroku provides an excellent tutorial on running Node.js applications on Heroku, it falls short in demonstrating the full potential of the platform.

This series, starting with an empty folder, walks you through building a more complete solution that has a database, unit tests, and an automated workflow with the following environments:

• local (per developer)
• development (per pull request)
• staging
• production

Requirements

• Heroku Account
• Node.js Software: JavaScript runtime
• GIT Software: Distributed version control system
• GitHub Account: GIT repository sharing hub
• Heroku CLI Software: Heroku command line interface

Create Node.js Application

You start with a Node.js application; in this case, we create the simplest hello-world application.

Create a folder (in my case, I called it hello-heroku) and run the following command in it (accepting all defaults) to initialize the project.

npm init

It will generate a singe file in the project folder, e.g.,:

package.json

{
  "name": "hello-heroku",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

note: Up until very recently, I was using an alternative Node.js package manager called Yarn (but now the built-in Node.js package manager solves the problems that drove many to Yarn in the first place).

Next, let us write the most basic Node.js application (straight from the Node.js about page).

index.js

const http = require('http');
const hostname = '127.0.0.1';
const port = 3000;
const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello World\n');
});
server.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`);
});

We can run the Node.js application with the following command (and then view it using a web browser at the provided URL).

node index.js 

GitHub Repository

After creating a GitHub repository using the New repository button, we follow the instructions provided by GitHub to create a new local repository from the command line. For example in my case, using the following commands from the project folder:

echo "# hello-heroku" >> README.md
git init
git add README.md
git commit -m "first commit"
git remote add origin https://github.com/larkintuckerllc/hello-heroku.git
git push -u origin master

To track (add to our repository) our index.js and package.json files we use the following commands:

git add index.js
git add package.json
git commit -m "add application"
git push origin master

Create Heroku Application

The Heroku Application is essentially a bundle of everything that your solution needs to run (even includes things like a supporting database service).

To prepare our earlier code to run in a Heroku application, we only have to modify the Node.js application to run on any host using a port supplied through the process’ environment; otherwise falling back to port 5000.

index.js

const http = require('http');
const PORT = process.env.PORT || 5000;
const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello World\n');
});
server.listen(PORT, () => {
  console.log(`Server running on ${PORT}/`);
});

We also want to update package.json to match your Heroku application Node.js version to what you have installed locally; revealed with the node -v command. This ensures that your local and Heroku environments more closely match.

package.json

{
  "scripts": {
    "start": "node index.js",
    ...
  }
  ...
  "license": "ISC",
  "engines": {
    "node": "9.2.1"
  }
}

note: Added the start script on 11/14/18 as it would crash without it.

We also need to create a file to define the processes (and associated entry points) that will run in the application. In this case we have a singular web process that is started from the command node index.js.

Procfile

web: node index.js

With these changes in place, we can create the Heroku application using the following command (in my case, naming the application hello-heroku-staging).

heroku create hello-heroku-staging

In addition to creating the Heroku application, this command sets a GIT remote that we will push to; as seen by the command:

git remote -v 

with output (in my case):

heroku https://git.heroku.com/hello-heroku-staging.git (fetch)
heroku https://git.heroku.com/hello-heroku-staging.git (push)
origin https://github.com/larkintuckerllc/hello-heroku (fetch)
origin https://github.com/larkintuckerllc/hello-heroku (push)

We then push the local master branch to Heroku using the command:

git push heroku master

At this point, we can open the application in a browser by using the Open app button on the Heroku application dashboard; or from the command line:

heroku open 

With this in place our workflow is:

1. Develop and test locally
2. Push changes to GitHub (origin) master
3. Push changes to Heroku (heroku) master; triggering Heroku to build the staging (doubling as production) application.

Next Steps

At this point, you have created and installed a Node.js web service into a Heroku application with a simplified workflow. In the next part, Node.js on Heroku: A More Complete Tutorial: Part 2, we will develop a more robust workflow.