Heroku Node.js Build Script Change FAQ

Issue

This document covers additional questions about the Node.js Build Script change described in the CHANGELOG

Resolution

What is the change?

The official Heroku Node.js buildpack will now execute your Node.js app's build script if it is defined in the app's package.json file. This makes it even easier to get started on Heroku with tools like webpack, create-react-app, Next.js, Vue.js, and many others.

  "scripts": {
    "start": "node src/index.js",
    "build": "webpack" // This will now run on Heroku by default
  }

Why the change?

This change supports community conventions that have emerged in the past few years. Nearly every frontend build tool now instructs users to use the build script when getting started. These tools include:

• create-react-app
• Next.js
• Gatsby
• webpack
• Vue.js

Do I have to change my package.json config?

Some apps do need to be updated. If your app defines a build script that you do not want to be executed on Heroku, you can define a heroku-postbuild script, which will be run instead:

"scripts": {
  "start": "node index.js",
  "build": "webpack",
  "heroku-postbuild": "echo Skip build on Heroku"
}

What will happen if I don't update my app?

If your app doesn't define a build script, then it will not be affected.

If your app does already define a build script, the most likely result is that the script will be executed twice, resulting in a longer build.

What if I don't want my "build" script to run on Heroku?

If your app also defines a heroku-postbuild script, it will run instead of the build script:

  "scripts": {
    "start": "node src/index.js",
    "build": "webpack",
    "heroku-postbuild": "webpack --config webpack.config.prod.js"
  }

You can use this to overwrite the build script if you'd like. If you need a build script but don't want it to run on Heroku, you can simply add an empty heroku-postbuild script.

  "scripts": {
    "start": "node src/index.js",
    "build": "webpack",
    "heroku-postbuild": "echo Skip builds on Heroku"
  }

My app is using "postinstall" to run its build step on Heroku. Is that okay?

Yes! The postinstall script has the drawback of being executed anytime you install dependencies with yarn or npm. It's common to want to build your app slightly differently in production versus when you are developing locally, so we believe that the build and heroku-postbuild scripts are a better solution. If you are already using postinstall today it will not stop working.

Please be aware that if you have both a postinstall script and a build script that both will be executed when Heroku builds your application.

I need more time to update my app!

However, if you need more time, you can pin your app to an older version of the Node.js buildpack with the following command:

$ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-nodejs#v134 -a my-app

Alternatively, you can modify the "Buildpacks" section on your app under "Settings" in the Heroku Dashboard.