Developing Node.js apps on GitHub and Heroku

Most development work is done locally on a developer’s workstation, but there will come a time where you need to share your work with others. Sharing an app on internal infrastructure is painful and wastes precious time. Setting up a VM in the cloud may be necessary for production, but is overly expensive and complex for testing purposes. PAAS (platform as a service) options are a cheap and fast way to get eyes on your app as soon as possible.

As far as PAAS providers go, Heroku holds the ease of use crown and offers a very good free tier, making it the best choice for this task.

To most effectively leverage the automation possible through this setup, we need to have our code in source control. GitHub is going to be the easiest way to get an app up and running on Heroku, and you’re probably using it anyway.

Getting started

We’ll be starting with a very basic “Hello World” Express app for the purposes of this guide. You can fork or clone my sample app if you want to follow along, though this same process applies to any Node webapp so feel free to use your own.

I'm assuming that the app you want to deploy is already up on GitHub.

Package.json

Heroku uses your package.json to determine how to start your app and what version of Node to use:

{
  "name": "hello-express",
  "version": "0.0.1",
  "description": "Simple Hello World app in Express.",
  "scripts": {
    "start": "node ./app.js"
  },
  "engines": {
    "node": "^6.9.2"
  },
  "dependencies": {
    "express": "^4.14.0"
  }
}

The first thing we need to make sure we have is a start script:

"scripts": {
  "start": "node ./app.js"
}

Heroku runs $ npm start to start your app, so whatever you have in that script is what will be run when it's deployed.

The other important thing to specify is the engine you want to use. This allows you to specify the version of Node Heroku should use to run your app. Heroku will choose a sensible default but, I consider it almost mandatory to specify this yourself to prevent future compatibility issues:

"engines": {
  "node": "^6.9.2"
}

For this app, I have specified that Heroku should use version 6.9.2 of Node (the most recent LTS at the time of writing), or the latest patch of 6.9.x (if a newer one is available).

PORT environment variable

While Heroku can do some black magic to automatically redirect requests to the port your app is running on, most other cloud providers don't. It's a good idea to use the port that Heroku and any other cloud provider provides for you to use by setting your app to make use of the PORT environment variable:

const express = require('express')

const app = express()  
const port = process.env.PORT || 8080

app.get('/', (request, response) => {  
  response.send('Hello Express')
})

app.listen(port, () => {  
  console.log(`Hello Express listening on port ${port}`)
})

As you can see in the sample project, simply reference process.env.PORT when deciding where to listen.

Deploying

At this point we have our project up on GitHub and have made sure our package.json has a start script and engines defined. The next step is to get our app live on Heroku. If you don't have one already, create a Heroku account.

We'll be starting on the "Personal apps" page:

Create a new app by selecting "New" -> "Create new app":

Give it a name, and then create the app:

You should now be on the "Deploy" tab for your app. Select "GitHub" as the deployment method, search for your repository, and click "Connect":

Scroll down to the "Manual deploy" section and click "Deploy Branch".

You will see a virtual console detailing the build and deploy steps. If the build is successful, you should see a button that says "View". Click this button to go to your hosted web app:

You will be brought to the root of your app and should see whatever that route returns (in my case, the text "Hello Express"). The URL for this app is constant so it can be shared with anyone you want to see your app:
Deployed

Automatically deploying

While getting an app deployed on Heroku is easy, it's a pain to have to go to Heroku every time you want to deploy changes. For the ultimate in productivity, we can have Heroku automatically deploy your app every time you push up a change to GitHub. This of course means that you need to make sure that the code you push up is always in a deployable state, making this impractical for production use, but invaluable for development.

On your app's "Deployment" tab, scroll down to the "Automatic deploys" section, and click "Enable Automatic Deploys":

With this enabled, every time you push up to your master branch on GitHub, your app will automatically be deployed to Heroku.