Deploying to Heroku using Gulp, Node, and Git

Share this article

Whether you’ve used it or not you’ve probably heard about Heroku at some point wandering around the Web. Heroku lets you deploy, run, and manage projects written in Ruby, Node.js, Java, Python, Clojure, Scala, and PHP. This platform brings joy to so many developers because of its amazing build packs that create a robust deployment workflow.

Heroku Deployment

Let’s examine the required files needed to deploy a project to Heroku using Gulp, Git, and Node.

Heroku Terminology

Before we begin, we’ll make sure a few bits of terminology are defined.

A lightweight Linux container that runs a single user-specified command. A dyno can run any command available in its default environment. Read more about Dyno types here.
These lie behind the slug compilation process. They’re open source, enabling you to extend Heroku to other languages and frameworks. Buildpacks take your application, its dependencies, and the language runtime, and produce slugs.
A bundle of your source, fetched dependencies, the language runtime, and compiled/generated output of the build system – ready for execution.

File Requirements

In order to run a Node-based project on Heroku, we need a few things to get started. The first thing we need is a project. For our purposes, we’ll use the Transformicons Open Source project as the example for this tutorial. You can also use the Transformicons repo with your own free Heroku account to practice outside this article!

Make a Procfile

Begin by making a blank file named Procfile and placing it within the root of your project. Procfile is short for “Process File” and used to explicitly declare what command should be executed to start your app. By default, a Procfile is not required, but it’s good form for Node-based projects to create one.

If a Procfile isn’t defined, then one will be created automatically using npm start as the web process type. Here’s the Procfile process command for Transformicons:

web: node node_modules/gulp/bin/gulp build

The line above lets us use the locally installed version of Gulp provided by Node’s Package Manager (NPM) instead of having to use a globally installed version. The gulp build portion of that command in this case will fire up a server, compile Sass, concatenate / uglify JavaScript, replace asset calls, cache bust file names, compile templates with Assemble, and finally minify our compiled HTML documents! This is the part where we dance our pants off

Create a Production Server

For those using Gulp to serve assets, you can use the following task in your gulpfile.js to fire up a static server for Heroku in order to view the deployed project in a browser.

gulp.task('serveprod', function() {
    root: [your_project_path],
    port: process.env.PORT || 5000, // localhost:5000
    livereload: false

Developers also have the option of using something like a Node-based server if desired, but for this discussion we’ll use Gulp to handle that for us.

Define the Correct Dependencies

Gulp requires the presence of a package.json file within the root of your project’s directory. Inside this file you must note whether the dependencies defined are installed or not. By default, Heroku config is set to production and will install dependencies from the dependencies object.

devDependencies for tasks such as gulp clean, like in the case below, will not install on the production environment. Using the example below, notice I require many items under dependencies that are necessary for deployment, like minification, concatenation, and anything that generally helps to build the project files themselves.

  "dependencies": {
    "gulp": "^3.8.10",
    "gulp-autoprefixer": "^1.0.1",
    "gulp-concat": "^2.4.1",
    "gulp-connect": "^2.0.6",
    "gulp-extname": "^0.2.0",
    "gulp-load-plugins": "^0.7.0",
    "gulp-minify-html": "^0.1.8",
    "gulp-rev": "^2.0.1",
    "gulp-sass": "^1.2.2",
    "gulp-template": "^1.1.1",
    "gulp-uglify": "^1.0.1",
    "gulp-usemin": "^0.3.8",
    "gulp-util": "^3.0.1",
    "assemble": "git://",
    "lodash": "^2.4.1",
    "marked": "^0.3.2"
  "devDependencies": {
    "gulp-clean": "^0.3.1"

Deploy to Heroku

Now that your project has the required files in place for deployment to Heroku, download the Heroku toolbelt and install it on your machine. The Heroku command-line client will install to /usr/local/heroku and /usr/local/heroku/bin will be added to your PATH. Assuming you already have a username and password with Heroku, begin by logging in to your Heroku account from the shell.

heroku login

Once logged in, run the following commands in the order that follows (assuming your project has a git repo initialized).

cd [mysitedir]
heroku create
git push heroku master
heroku open

The heroku create command creates a new application on Heroku – along with a Git remote that must be used to receive your application’s source. Make sure your code (especially any changes that are not present on your remote repository) is pushed to GitHub (or Bitbucket if you choose) before you deploy to Heroku, otherwise changes will remain undetected when git push heroku master is executed.

If you need to check production code, you can always use foreman start from the shell to test instructions and functionality for deployment on your local machine. If you’re curious what the deployment logs look like for Heroku, feel free to check out this CodeShare.

Heroku GitHub

Note for GitHub users: Heroku is limited to a rolling window of 75 Git requests per hour, per user, per app. Once this limit is reached, in order to protect the Git service, Git requests are denied for a few minutes until request levels drop below the limit.

Looking Back

Lets take a look at what’s happened up until this point and why Heroku is so cool for deployment. Most importantly, we’ve prevented production code from entering our GitHub repo, ultimately avoiding future merge conflicts that can and will occur often with compiled code.

We’ve also managed to concatenate, minify, and cache bust file references purely for deployment purposes. This approach prevents us from manually writing our replacement references within each individual document. All these tasks are completed automagically by machines! Now let’s get rid of that domain name.

Custom Domain

For those that desire a custom domain name you should be aware that it’s not possible at the time of this writing to remove the www
, so it’s good form to forward calls from non www references to the www reference if you desire that behaviour.

Domain Heroku

To create a custom CNAME, simply add the domain to your CNAME record followed by name forwarding, should you choose to do so.

Additional Notes

Heroku users should take the time to understand the buildpack-api caching explanation that also clarifies a bit on how the flow works with Heroku projects. If at any time you need some “heroic” help via the command-line, you can always type heroku help to get a list of options available.

With regards to Gulp, there may be times when you require to be all “Bill Murray” and control Gulp’s streams as you deploy, ensuring one process has completed before another begins. In order to ensure one task completes before another begins, give your src line a var named stream and return the stream once your task pipes are completed.

This ensures that one task knows when another completes, avoiding simultaneously running in parallel. Here’s an example of what that looks like:

gulp.task('sass', function() {
  var stream = gulp.src(paths.sitesass + '/**/*.scss')
      browsers: ['last 2 versions'],
      cascade: false

  return stream; // return stream to notify us of completion

gulp.task('cssmin', ['sass'], function() {
  var stream = gulp.src(paths.sitecss + '/*.css')

  return stream; // return stream to notify us of completion


A productive workflow and the tools that help make deployment a breeze are essential to any developer’s arsenal. Whatever the tool is, make it the best it can be and don’t be afraid to break habits in order to venture into the unknown. Get started right now and empower your workflow and deployment methods.

Further Reading

Frequently Asked Questions on Deploying Heroku Using Gulp, Node & Git

How can I troubleshoot common issues when deploying on Heroku using Gulp, Node & Git?

Troubleshooting issues when deploying on Heroku using Gulp, Node & Git can be done by checking the logs. Heroku provides a command heroku logs --tail that allows you to view real-time logs. If you encounter an application error, you can use this command to identify the problem. Additionally, ensure that your package.json file has the correct start script and that all necessary dependencies are included. If you’re using Gulp, ensure that your gulpfile.js is properly configured.

How can I manage environment variables in Heroku?

Environment variables in Heroku can be managed through the settings tab of your Heroku dashboard. Here, you can reveal your config vars and add new ones. You can also use the Heroku CLI to manage your environment variables. The command heroku config:set VARNAME=value allows you to set a new variable, and heroku config:unset VARNAME allows you to delete a variable.

How can I deploy a Node.js application with a child process in Heroku?

Deploying a Node.js application with a child process in Heroku requires a Procfile. A Procfile is a text file in the root directory of your application that defines process types and explicitly declares what command should be executed to start your app. For example, if you have a worker process, your Procfile might look like this: worker: node worker.js.

How can I scale my Node.js application on Heroku?

Scaling your Node.js application on Heroku can be done by adjusting the number of dynos – lightweight containers that run the command specified in the Procfile. You can scale your application by using the heroku ps:scale web=1 command, where ‘web’ is the name of the process type defined in the Procfile, and ‘1’ is the number of dynos.

How can I update my Node.js version on Heroku?

Updating your Node.js version on Heroku can be done by specifying the version in your package.json file. You can specify the version in the “engines” field. For example, "engines": {"node": "14.x"}. After updating the package.json file, you can push the changes to Heroku.

How can I use Gulp tasks in Heroku?

To use Gulp tasks in Heroku, you need to include Gulp in your package.json dependencies and define a postinstall script. The postinstall script will run after your application is deployed on Heroku. For example, "scripts": {"postinstall": "gulp build"}.

How can I rollback to a previous version of my application on Heroku?

Rolling back to a previous version of your application on Heroku can be done by using the heroku releases:rollback command. This command allows you to rollback to the previous release, or you can specify a release by appending the release number, for example, heroku releases:rollback v23.

How can I use Git to deploy my application on Heroku?

To use Git to deploy your application on Heroku, you need to initialize a Git repository in your application directory using git init. Then, you can add Heroku as a remote using heroku git:remote -a your-app-name. After making changes to your application, you can use git add ., git commit -m "message", and git push heroku master to deploy your application.

How can I use a custom domain with my Heroku application?

To use a custom domain with your Heroku application, you need to add the domain to your application through the Heroku dashboard or using the Heroku CLI with the command heroku domains:add Then, you need to configure your DNS provider to point to the Heroku-provided DNS target.

How can I monitor the performance of my Node.js application on Heroku?

Monitoring the performance of your Node.js application on Heroku can be done by using Heroku’s metrics dashboard. The metrics dashboard provides information about your application’s response times, throughput, memory usage, and CPU load. You can also set up alerts to be notified when your application exceeds certain thresholds.

Dennis GaebelDennis Gaebel
View Author

Design Technologist passionate for Open Source, SVG, Typography, Web Animation and Interaction Development.

Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week
Loading form