React.js is a very powerful front-end framework, as its popularity and adoption over the years have shown. However, building a full, production-level application involves a feature set that the React framework, on its own, doesn’t include. Features like routing, code-splitting, bundling, CSS modules, and more are needed for production-level application development. These are not capabilities that React.js offers out-of-the-box. This is where Next.js comes in.

Next.js is the React framework for production as advertised on the Next.js official website. It provides production-level features to React.js developers to easily build production-ready apps.

In this tutorial, you will learn how to automate the deployment of Next.js applications to Heroku.


To follow this tutorial, a few things are required:

  1. Basic knowledge of Javascript
  2. Node.js installed on your system (version >= 10.3)
  3. An Heroku account
  4. A CircleCI account
  5. A GitHub account

With all these installed and set up, let’s begin the tutorial.

Creating a Next.js project

To begin, create a new Next.js project by running the following command:

npx create-next-app next-cd

This will automatically create a Next.js application inside the next-cd folder (you can give the folder any name you chose). Once the scaffolding process is done, go into the root of the project and run the application with the following commands:

cd next-cd
npm run dev

This will boot up a development server that serves the application at its default 3000 port (http://localhost:3000). Load this URL in your browser and you will see the default homepage.

New App (Local) - Next.js

Creating an Heroku app

The next step is to set up a Heroku application to host our app. Navigate to your Heroku account management console, go to New -> Create new app, and create a new app with your preferred name.

New App - Heroku

Take note of the app name you just entered. You will need this later.

Next, locate your Heroku API Key in the Account Settings section of your dashboard. You will also need this later in the tutorial. You can access Account Settings from the dropdown menu that appears when you click on your avatar at the top right of the webpage.

Setting up a CircleCI project for deployment

To set up your project on CircleCI, you need to initialize your project as a git repository (if it isn’t already initialized).

Then, create a remote GitHub repository for the project, commit your changes (if any), and push the local project to the remote repository.

Next, go to the Add Projects page on the CircleCI dashboard to add the project.

Add Project - CircleCI

Click Set Up Project.

Add Config - CircleCI

On the set-up page, click Use Existing Config to instruct CircleCI that we will add a configuration file manually, and not use the sample config displayed. Next, you get a prompt to either download a configuration file for the pipeline or start building.

Build Prompt - CircleCI

Click Start Building. This build will fail because we have not added our configuration file yet. We will do that later.

The final thing we need to do on the CircleCI console is set up environment variables for the project we just added. This will enable our project to have authenticated access to our Heroku application for deployments.

Go to your project’s settings by clicking Project Settings on the Pipelines page (make sure your project is the currently selected project).

Project settings - CircleCI

On this page, click Environment Variables on the side menu. Then click Add Environment Variable.

Add Environment variable - CircleCI

Add the following environment variables:

  • HEROKU_APP_NAME: This is the name of your Heroku application (in my case, next-cd).
  • HEROKU_API_KEY: Your Heroku account API key. This can be found under the Account tab on Heroku, under Account Settings.

Once added, you now have everything set up on your CircleCI console for deployment to Heroku.

Automating the deployment of the Next.js application

Now we can begin the process of building the automation script for the deployment of the Next.js application to Heroku.

You need to create a Procfile file containing instructions for Heroku to build and start the application. Create a file named Procfile (no file extension) at the root of the project, and enter the following:

npm run build
NODE_ENV=production npm run start

The first command in this file creates a production optimized version of our Next.js application. The next command starts the application in production mode.

Now we need to ensure that Heroku uses a dynamic port in production. Make this little change to the start script in package.json:

"start": "next start -p $PORT"

With this, our Next.js application will now use the dynamic $PORT variable set by Heroku in production.

Finally, we create our deployment script for CircleCI to build our deployment automation pipeline. In this script, we use CircleCI’s Heroku orb to deploy our application from our GitHub repository straight to Heroku. Orbs are easy-to-use packages that abstract a lot of boilerplate and sometimes complex commands/workflows providing a developer-friendly API for use in our configuration files.

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

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

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 job, which deploys your application straight from your GitHub repo to your Heroku account. This job already takes care of installing the Heroku CLI, installing project dependencies, running the build script, and deploying the application. It also picks up our environment variables to facilitate a smooth deployment to our Heroku application.

It’s now time to test our work so far. Commit all changes to the project and push to your remote GitHub repository. This will automatically trigger the deployment pipeline.

Build Successful - CircleCI

By clicking on the build, you can see the deployment details.

Build Details - CircleCI

Don’t start the parade yet, sometimes a successful build doesn’t exactly equate to a successful deployment. There are still many things that can go wrong on the Heroku platform itself. To confirm that we have a successful deployment, go to your Heroku application dashboard and click Open app. This will open the application at the Heroku-designated URL (https://[APP_NAME] The default homepage below confirms a successful deployment. Yippee!

Site Live - Heroku

Now, let’s confirm that our changes are automatically deployed when we push them to our remote repository. Change the h1 tag in ./pages/index.js from:

<h1 className={styles.title}>
    Welcome to <a href="">Next.js!</a>


<h1 className={styles.title}>
    Welcome to <a href="">My Next.js! Site</a>

Then commit and push the changes to trigger another deployment. Once the build is successful, refresh your live site and you will see the screen below.

Site Live - Heroku


Deploying little to large changes to an application by following a manual deployment process can quickly become a frustrating and laborious process. With CircleCI, you can automate the process, eliminating any worry about routine or human errors introduced by manual processes. In this tutorial, we have been able to successfully create an automated deployment pipeline to achieve seamless deployments for any change to our application, making them one less thing to worry about.

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.