CircleCI orbs are reusable packages of YAML configuration that condense repeated pieces of config into a single line of code. Since its launch in 2018, the CircleCI orbs registry has experienced massive growth with packages published internally by the CircleCI team, by developers, and by companies who want to help developers integrate their services seamlessly into continuous integration pipelines.

In this article, we will demonstrate how to continuously deploy a Node.js application to Heroku, one of the most popular hosting platforms, using CircleCI orbs.


In order to follow along with this post, you will need a few things in place:

  • Node.js installed on your system (you can confirm this by running the command node -v on your terminal to print out your version of Nodejs installed).
  • Git installed on your system (you can confirm this by running the command git on your terminal, this should print out available git commands)
  • A Heroku account
  • A GitHub account

With these, you are ready to follow along with the tutorial.

Cloning a Node.js API project

The application we are going to be hosting on Heroku is a simple Node.js API project consisting of a single route that returns a list of to-dos.

As this exercise is focused on deploying an application to the Heroku platform, there is no need to bother with the details of creating a new Node.js application, we can just clone a ready-made one from this repo. Simply run the following command to clone the project:

git clone

This will clone the Express.js API project onto our system. The entry point for this application is the server.js file which contains the code below:

const express = require("express");
const routes = require("./routes");

const app = express();
const port = process.env.PORT || "1337";
app.set("port", port);

app.use('/', routes);

app.listen(port, () => console.log(`Server running on localhost:${port}`));

In the file above, a new Express.js application is created and exposed at port 1337. The application is then set to use routes defined in the routes.js file.

The routes.js file shown below creates a new Express.js router and exposes a single /todos route which returns an array of to-do items defined in the todo.js file. It then exports the router object.

const express = require('express');
const todos = require("./todos");

const router = express.Router();

router.get("/todos", function(req, res) {

module.exports = router;

Let’s take the project for a spin by first installing the dependencies by typing the following command in the project’s root:

npm install

Then run the application with the command:

node server.js

The application should now be up and running at the address http://localhost:1337. Open up your preferred browser and visit the /todos route at http://localhost:1337/todos. You should see a screen similar to the one below (browser magnification at 150%):

As seen above, the route returns an array of todo objects each with an id and task name.

Now create a new repository for this project on your GitHub account and push the project to the repository you just created.

Preparing the Node.js project for deployment

If not specified (by creating a Heroku Procfile), Heroku starts a Node.js project with the npm start command which indicates that Heroku requires a start script in our package.json file for it to start our application.

Thus, we need to create a start script in our package.json file to instruct Heroku on how to start the application. Simply go into the scripts section of package.json (currently contains only one test script ) and add the start script as shown below (this has already been added in the cloned project):

“scripts” : {
	“start”: “node server.js”


With this in place, Heroku can now start our application successfully.

Creating an application on Heroku

The next step in the process is to create a Heroku application. This application will map to our deployment and help us manage our deployed application. It will provide features such as metrics, scaling capabilities, and access to application logs.

Head over to your Heroku dashboard and create a new application by clicking New and selecting Create new app.

This will bring up the app creation form as shown below:

For this app, we have given it the name my-heroku-node-api, but feel free to give it any name of choice making sure the name does not contain spaces or characters that are not URL-friendly in between.

Click Create app to set up your new application.

Setting the project on CircleCI

The next step to deploying our application to Heroku is to connect the application in our GitHub repository to CircleCI.

Head over to your CircleCI dashboard and add the project in the Add Project section.

Next to your project (in this case simple-node-api), click the Set Up Project button. This should bring you to a page similar to the one below:

Click Start building to begin setting up the project. This will immediately give us an error indicating that a CircleCI configuration file cannot be found in the project.

This is understandable as we have yet to include our pipeline configuration file. We will be doing that later in the tutorial.

Configuring Heroku access on CircleCI

In order to push our project to Heroku from CircleCI, we need to configure an authenticated handshake between CircleCI and Heroku. This is done by creating two environment variables in the settings for your CircleCI project. These two environment variables are:

  • HEROKU_APP_NAME: This is the name of your Heroku application (in this case my-heroku-node-api)
  • HEROKU_API_KEY: Your Heroku account API key. This can be found under the Account tab of your Heroku account under Account Settings. Scroll down the Account tab to the API Key section and click Reveal to copy your API key.

Once you have gotten these details, head over to your CircleCI dashboard and click Settings for your project:

On the sidebar menu on the settings page, click Environment Variables under Build Settings.

On the environment variables page, create two variables named HEROKU_APP_NAME and HEROKU_API_KEY and give them their respective values.

With these in place, our CircleCI configuration will make use of them to make authenticated deployments to the Heroku platform.

Adding the deploy configuration

Now to the main action area - our deploy pipeline. Let me let you in on a little secret, this is going to be the easiest step. Did that just put a smile on your face? I would like to believe so!

Believe me, this step is not easy with just any CI tool, but with CircleCI orbs, we are about to work magic. The CircleCI orbs registry has a ready-made orb for deploying applications to Heroku, the Heroku orb. We will be using this orb in our CircleCI configuration to deploy our application to Heroku.

At the root of your project, create a folder named .circleci and within it, create a file named config.yml and add the following configuration:

version: 2.1
  heroku: circleci/heroku@0.0.10
      - heroku/deploy-via-git

Oh? Is that everything? You bet it is! Remember, I told you we would work magic.

In the configuration above, we pull in the Heroku orb circleci/heroku@0.0.10 which automatically gives us access to a powerful set of Heroku jobs and commands.

One of those jobs is the heroku/deploy-via-git which deploys your application straight from your GitHub repo to your Heroku account.

Right now, you might have a few questions. How was the Heroku CLI installed. When was the code checked out of the repo? How were the authentication credentials accessed? When did Heroku’s deployment command run?

This is where the true power of orbs shine. All processes in the questions above have already been abstracted by the Heroku orb. Pulling in the orb ensures that we have an environment set up for deployment to Heroku while the job checks out our code, deploys it to Heroku, and starts the application. It abstracts the nitty-gritty of the process.

Save the configuration and push your changes to your GitHub repository. This should immediately trigger the deployment process to Heroku via CircleCI. If the instructions have been accurately followed, you will see a successful pipeline run on your dashboard as shown below:

To get a view into what the Heroku orb did behind the scenes, click on the build process and you will see the following steps:

You didn’t have to define these steps, the orb took care of everything for you.

To confirm that the application has been successfully deployed and is now running, visit the link For this tutorial, this will be This will return our list of to-dos as expected. I have used a JSON formatter plugin for Firefox for better visibility as shown below:

And there you have it. The Node.js API project has been successfully deployed to Heroku in very few steps through the power of CircleCI orbs.


CircleCI orbs is a revolutionary product in the CI/CD world. Abstracting a lot of tedious, error-prone boilerplate configuration code to provide simple, stable, and powerful abstractions helping you focus on the main task at hand deploying applications successfully.

Feel free to check the CircleCI orbs registry for orbs that suit your programming language and deployment of choice. With CircleCI orbs, you don’t need to reinvent the wheel.

Happy Coding :)

Fikayo is a fullstack developer and author with over a decade of experience developing web and mobile solutions. He is currently the Software Lead at Tech Specialist Consulting and develops courses for Packt and Udemy. He has a strong passion for teaching and hopes to become a full-time author.