Table of Contents [expand]

• Additional Reading

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

Additional Reading

• Deploying Front-End Web Apps on Heroku
• Front-End Web Buildpack repo