How to setup a Node.js app with a custom start and build script on Heroku

These days, the cloud has made it easier for anybody to launch a website or app. One of those services is Heroku, a platform that allows websites to be deployed on runtimes such as Node.js.

Heroku allows you to publish your web application with just one click. And if you're familiar with it, then you already know that you can use shell scripts or launch commands in the terminal to deploy your applications to the cloud. But what if you have a specific build or start script that you might want to run solely on Heroku?

In this article, I will teach you how to set up your Node.js application on Heroku using a build and start script of your choice!

Heroku-specific build script

If your app has a build step that you’d like to run when you deploy, you can use a build script in package.json (since March 2019, Node.js deployments will automatically execute an app’s build script during the deployment if one is defined in the app’s package.json file).

"scripts": {
  "start": "node index.js",
  "build": "webpack" // this will automatically run on Heroku
}

If you want to define some other script rather than build to run specifically on Heroku, you can add a heroku-postbuild to your package.json scripts, which will run instead of the regular build script.

"scripts": {
  "start": "node index.js",
  "build": "ng build", // will not run on Heroku
  "heroku-postbuild": "ng build --prod" // if provided, this will run instead
}

You may also want to run scripts only before or after other Heroku build steps. For instance, you may need to configure npm, git, or ssh before Heroku installs dependencies, or you may need to build production assets after dependencies are installed.

To achieve these Heroku-specific actions, you can use the following scripts:

• heroku-prebuild:
  • Runs before Heroku installs dependencies.
• heroku-postbuild:
  • Runs after Heroku installs dependencies (but before pruning and caches dependencies). If this script is specified, the regular build script will not run.
• heroku-cleanup:
  • Runs after Heroku prunes and caches dependencies.

Heroku-specific start script

By default, Heroku runs npm start while starting deployed Node.js applications, but if you would like to run some other script from your package.json instead you just need to follow one simple step.

Just create a Procfile at the root of your project with your custom start script:

web: npm run my-custom-start

And that's it! Now Heroku will run my-custom-start instead of the regular start script when you deploy your Node.js app.

"scripts": {
  "start": "node index.js", // will not run on Heroku
  "my-custom-start": "PROD=true node index.js" // this will run instead
}

Setting up a Node.js app on Heroku is easy, but still requires some setup to ensure that your app build and starts properly.

Hopefully, this small guide could help you customize your Heroku app to your specific needs and make your deployment process faster. Thanks!

Hey! 👋 My name is Diogo and I'm an enthusiastic frontend developer who is passionate about building for the web. If you want to keep in touch check out my website or follow me on Twitter.