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?

Beginning March 11th, the official Heroku Node.js buildpack will execute your Node.js app's build script if it is defined in the app's package.json file. This will make 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:

Do I have to change my package.json config?

Some apps do need to be updated. We've published an npm package that will walk you through suggested changes and make the changes for you. You can run it with one command in your app's root directory:

$ npx @heroku/update-node-build-script

screenshot of the CLI tool working

Do I have to wait until March 11 to make this change?

No, you can opt-in to the change anytime before then by setting the heroku-run-build-script key in your package.json. Opting in now will prevent any disruption to your workflow when this change is rolled out.

Running npx @heroku/update-node-build-script will help you make this change if your app will be affected.

"scripts": {
    "start": "node src/index.js",
    "build": "webpack"
},
"heroku-run-build-script": true

You may remove the heroku-run-build-script key whenever you like after March 11th. A warning will be added to the build log reminding you that it is no longer necessary once the change is made.

How will I know the change was successful?

When you build on Heroku, you will see this new message at the bottom of your build log once you have opted in to the change:

-----> Opting in to new default build script behavior
       You have set "heroku-run-build-script"=true in your package.json
       Your app will be unaffected by the change on March 11, 2019

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!

We would like to stress that we have provided a CLI tool that can update your app with one command that shouldn't take more than a minute:

$ npx @heroku/update-node-build-script

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.

npx is not installed on my system

npx usually comes bundled with npm in most Node installations, however there may be some users who do not have it installed.

In that case you can install it with npm itself:

$ npm install -g npx

or install and execute the script itself:

$ npm install -g @heroku/update-node-build-script
$ update-node-build-script

which can then be uninstalled from your machine with this command:

$ npm uninstall -g @heroku/update-node-build-script

Ask on Stack Overflow

Engage with a community of passionate experts to get the answers you need

Ask on Stack Overflow

Heroku Support

Create a support ticket and our support experts will get back to you

Contact Heroku Support
Terms of Service Privacy Cookies © 2019 Salesforce.com