Table of Contents [expand]
Last updated September 03, 2026
The Heroku Front-End Web Cloud Native Buildpack (CNB) is the recommended method for deploying static web apps on Heroku.
This migration guide is for you, if you want to update an existing app developed on Heroku using create-react-app-buildpack.
Heroku CI doesn’t support CNBs. If an app’s pipeline currently relies on Heroku CI, don’t migrate the app without a plan for how to migrate to a different CI system.
Create a Branch for Changes
In the app’s Git repo, create a branch to stage these changes:
git checkout -b migrate-to-frontend-web-cnb
Create project.toml
CNB configuration is set with the project.toml file:
[_]
schema-version = "0.2"
[[io.buildpacks.group]]
id = "heroku/nodejs"
# this installs Node.js and runs the build
[[io.buildpacks.group]]
id = "heroku/static-web-server"
# this hosts the website
[[io.buildpacks.group]]
id = "heroku/website-cra"
# this presets the document root and client-side routing
Based on any further customizations in static.json, fill out the project.toml, for example:
# response headers based on static.json "headers"
[com.heroku.static-web-server.headers."/"]
Cache-Control = "max-age=604800, stale-while-revalidate=86400, stale-if-error=86400"
[com.heroku.static-web-server.headers."/*.html"]
Cache-Control = "max-age=604800, stale-while-revalidate=86400, stale-if-error=86400"
[com.heroku.static-web-server.headers."/images/*"]
Cache-Control = "max-age=31536000, immutable"
See all configuration options of the static web server CNB. Not all static.json configuration is supported. Open an issue on GitHub to request features or report bugs.
Commit the new project.toml to the repo:
git add project.toml -m "Front-end Web CNB project config from create-react-app-buildpack"
git commit
Update app.json
For apps in pipelines that use Review Apps, you must update app.json. Set the stack to cnb and remove buildpacks:
{
"stack": "cnb",
"buildpacks": []
}
Commit the updated app.json to the repo.
Switch to the CNB Stack
To deploy using project.toml and the Front-End Web CNB, you must switch the app’s stack to cnb:
heroku stack:set cnb --app my-web-app
Every instance of an app from development, staging, and production requires setting the cnb stack. When using Heroku Pipelines, the stack gets updated along with promotions between stages.
Test CNB Deployment
Deploy the migrate-to-frontend-web-cnb branch to a non-production version of the app for testing. After the app builds and launches, verify that the app is working correctly.
Release CNB and Cleanup
After verifying with a non-production app, merge the branch, and deploy or promote to the production app.
After release, you can remove the previous create-react-app-buildpack or buildpack-heroku-static related files:
git remove static.json -m "Clean-up old config"
git commit