Hyphen
Log In

Cloudflare

Learn how to configure the Cloudflare integration in Hyphen to build, store, and deploy static sites using Cloudflare Workers and R2 storage.

The Cloudflare integration supports static sites, DNS, and traffic routes. Hyphen stores static builds in a private R2 bucket and publishes them through Workers Static Assets.

Table of Contents

Connect Your Account

Prepare Cloudflare

  1. Configure a workers.dev subdomain in your Cloudflare account.
  2. Enable R2 in that account.
  3. Create an account API token with the permissions below.
Scope Permission Purpose
Account Account Settings:Read Check account access.
Account Workers:Admin Create Workers and publish static sites.
Account Workers R2 Storage:Edit Create a private site registry and upload builds.
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 DNS and load balancers, grant access to each zone that Hyphen will manage. Static sites use the account's workers.dev subdomain without a custom DNS zone.

Add the Integration

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

Leave the jurisdiction field empty to use the default R2 endpoint. Hyphen manages R2 authentication with the account token; separate R2 access keys are not required.

The account test checks account access. It does not verify a file upload or a site deployment.

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. The deployment serves the site at https://<worker-name>.<account-subdomain>.workers.dev. Each environment or preview has its own Worker. Open the URL from the deployment's resources after the run succeeds.

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.
  • Include a root 404.html for a custom error page. Without it, a root index.html enables the single-page application 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

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.

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