Hyphen

Cloudflare

Learn how to connect Cloudflare to Hyphen to build, publish, and host static sites using Workers Static Assets and deploy Docker apps with Cloudflare Containers.

The Cloudflare integration supports static sites, Docker apps, DNS, and traffic routes. Hyphen publishes static sites through Workers Static Assets and runs Docker apps on Cloudflare Containers.

Table of Contents

Connect Your Account

Prepare Cloudflare

  1. Configure a workers.dev subdomain in your Cloudflare account.
  2. For static sites, enable R2 in that account.
  3. For Docker apps, enable Containers on a Workers Paid account.
  4. Create an account API token with the permissions for your use case.
Scope Permission Purpose
Account Account Settings:Read Check account access.
Account Workers:Admin Create Workers for sites, containers, and gateways.
Account Workers R2 Storage:Edit Create a private site registry and upload static builds.
Account Worker Containers:Edit Upload Docker images and deploy containers.
Account Account Analytics:Read Read static site request metrics.
Account Workers Observability:Write Query Worker and container logs (optional).
Account Load Balancing: Monitors And Pools:Edit Manage load balancer monitors and pools.
Zone Zone:Read Read DNS zones.
Zone Load Balancers:Edit Manage load balancers.
Zone DNS:Edit Manage DNS records.

Scope Workers:Admin to all current and future Workers in the selected account. Scope Workers R2 Storage:Edit to all current and future buckets. See Workers permissions for the provider's scope controls.

For custom hostnames, DNS, and load balancers, grant access to each zone that Hyphen will manage.

Add the Integration

  1. Open Integrations in your Hyphen organization.
  2. Select Cloudflare.
  3. Enter your Cloudflare Account ID.
  4. Enter the account token in API Token.
  5. If required, set R2 jurisdiction (optional) to eu, us, or fedramp.
  6. Select Test.
  7. Select Connect after the test succeeds.

Leave the jurisdiction field empty to use the default R2 endpoint. Hyphen uses the account token to manage R2 access.

The account test checks account access. Run a test deployment to verify build uploads and publication.

Application Telemetry

For static site request metrics, grant the account token Account Analytics:Read. Metrics cover complete minutes of the current deployment and can arrive late. If Hyphen reports that the site needs telemetry configuration, redeploy the site.

For optional log queries, grant the account token Workers Observability:Write. Enable persistent Worker logs in Cloudflare to collect Worker diagnostics. Requests that serve assets directly do not generate Worker invocation logs.

Hyphen can read available Worker and container logs for Cloudflare containers. Cloudflare container CPU, memory, and HTTP request metrics are unavailable in Hyphen.

Create a Site Registry

  1. Open your project's Settings → Integrations.
  2. Add a Site Registry connection for Cloudflare.
  3. Wait for the connection to reach Ready.

Hyphen creates a private R2 bucket for the project's builds. A project can have one active Cloudflare Site Registry. A Static Site connection represents the deployed site and its public URL. See Connection Types for these resource types.

Build and Deploy a Static Site

  1. Initialize your local app folder with hx init.
  2. Run your frontend build command to produce the website files.
  3. Open the project's environment deployment in Hyphen.
  4. Include the app with App Type set to Static.
  5. Select Cloudflare Workers under Deploy to.
  6. Save the deployment configuration.
  7. Run this command from the initialized app folder:
hx deploy --env production --type static ./dist

Replace production with your environment ID or alternate ID. Replace ./dist with your frontend output directory. The CLI requires finished files; it does not run the frontend build command or Docker.

To upload a build for a later deployment, run:

hx build --type static ./dist

To deploy an uploaded build, run:

hx deploy --env production --no-build --sites website:latest

Replace website with your app ID or alternate ID. The build must contain an artifact from the Cloudflare Site Registry for this project. The CLI uploads static files to every ready Site Registry on the project.

Hyphen reads the retained files from R2 and publishes a Worker version with static assets. Each environment or preview has its own Worker. The default URL is https://<worker-name>.<account-subdomain>.workers.dev. Open the site URL from the deployment resources after the run succeeds.

Set a Static Site Hostname and Path

  1. Connect an active Cloudflare zone in Settings → DNS → Add Zone. Use the same Cloudflare integration that hosts the site.
  2. Open the static app's deployment settings for the environment.
  3. Under Hostname, select the domain.
  4. To use a subdomain, enter it in Subdomain.
  5. To serve the site under a path, enter it in Path (optional).
  6. Save the settings.
  7. Run a deployment to apply the route.

For example, select example.com, enter docs as the subdomain, and leave the path empty to serve https://docs.example.com/. To serve https://example.com/docs/, leave the subdomain empty and enter docs as the path.

The gateway passes the full request path to the site. Set your frontend build's base URL to the same prefix. Put files for /docs/ under docs/ in the output directory. If you use a single-page app fallback, point it to /docs/index.html for this example.

Supported Files and Routes

This deployment type serves static files. It does not run server code or publish executable Worker bundles.

  • Include HTML, CSS, browser JavaScript, images, and other static assets in the output directory.
  • Supply a directory of regular files, without symbolic links.
  • Include _headers or _redirects at the directory root for custom headers or redirects.
  • By default, a root 404.html supplies the 404 page. If the root has no 404.html, a root index.html supplies the single-page app fallback.

Hyphen applies these limits to Cloudflare site builds:

Limit Maximum
Files per build 10,000
Size per file 25 MiB
Total file size 1 GiB

Set Static Site Rules in .hx

Use Hyphen CLI v0.33.0 or later. Add a top-level static object to the existing .hx file in your app folder. Keep the other keys that hx init added. This example configures a site at the root of a hostname.

{
  "static": {
    "headers": [
      { "path": "/*", "set": { "X-Content-Type-Options": "nosniff" } }
    ],
    "redirects": [
      { "source": "/old", "destination": "/new", "status": 301 }
    ],
    "spa": { "enabled": true, "fallback": "/index.html" },
    "notFoundPage": "errors/404.html"
  }
}
Key Effect
headers Set headers with set or remove them with remove. Each path starts with / and accepts one *.
redirects Match an exact source path. Set an absolute path or HTTP(S) URL as the destination. Use status 301, 302, 303, 307, or 308.
spa Return the fallback for browser navigation to a missing page. The default fallback is /index.html. Set enabled to false to turn it off.
notFoundPage Serve a file with status 404. Use a path relative to the output directory, without a leading /. Set it to null to clear it.

Include both fallback files in the build output when you set both options. If headers or redirects is present, it replaces the corresponding _headers or _redirects file. An empty array clears the corresponding rules.

Run hx build --type static ./dist or hx deploy --type static ./dist to record the rules with a new build. A deployment with --no-build uses the rules from the selected build.

Build and Deploy a Container

Use Hyphen CLI v0.33.0 or later. Run hx update to update an existing installation. Cloudflare requires Linux AMD64 images, which the CLI builds by default.

  1. Open the project's deployment settings for the environment.
  2. Include the app with App Type set to Container.
  3. Select Cloudflare under Deploy to.
  4. Select or create a Cloudflare Container Registry connection for the project.
  5. Set Scale and Availability for the app.
  6. Save the deployment configuration.
  7. Wait for the registry connection to reach Ready.
  8. In your app folder, run hx init if you need to link the folder to Hyphen.
  9. Run the deployment command:
hx deploy --env production

Replace production with your environment ID or alternate ID. Cloudflare uses the account registry without a Cloud Workspace. Temporary credentials for image uploads have account-wide access.

Hyphen uses one global Cloudflare resource per app, environment, or preview. Scale and Availability set a fixed pool size and a minimum number of warm replicas. Cloudflare controls placement and can put idle instances to sleep.

Check a Failed Build or Deployment

  • For a missing registry, check the project's Site Registry connection and its Ready status.
  • For a failed upload, check that R2 is enabled and the token has Workers R2 Storage:Edit access.
  • For a failed publication, check the workers.dev subdomain and the token's Workers:Admin scope.
  • For a missing artifact, upload the site again after the Cloudflare Site Registry is ready.
  • For a container registry that does not reach Ready, check that Containers is enabled and the token has Worker Containers:Edit access.
  • For a failed hostname attachment, check that the DNS zone is active in the hosting account. Check if another Worker already uses the hostname.

See Builds for build requirements and the CLI reference for static and container selections.