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:
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.