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.

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

Additional Reading

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