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.
Historically, Heroku users implemented an Nginx buildpack (heroku-community/nginx) to deploy static web apps on Heroku, following the Nginx for static sites guide. There are other ways to host a static site as well, including Node.js, Python, Ruby, Go, or any other supported language serving a directory of files over HTTP. Each language has their own unique setup.
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.
This guide covers how to migrate a static site from Nginx to the Front-End Web CNB.
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. Based on the contents of the app’s config/nginx.conf.erb, fill out a new project.toml, for example:
[_]
schema-version = "0.2"
[[io.buildpacks.group]]
id = "heroku/static-web-server"
# document root based on nginx "root" entry
[com.heroku.static-web-server]
root = "dist"
# client-side routing based on nginx "error_page 404" directive
[com.heroku.static-web-server.errors.404]
file_path = "index.html"
status = 200
# response headers based on nginx "location" blocks
[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 deeper, custom Nginx 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 based on nginx config"
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 Nginx-related files:
git remove config/nginx.conf.erb Procfile -m "Clean-up old nginx config"
git commit