Cloudflare Deployment Options

There are currently two realistic Cloudflare stories in this repo:

1. Simple static hosting
   • build with the regular CLI
   • publish the output yourself
2. Cloudflare adapter
   • scaffold with cloudflare-adapter
   • use the Worker + Static Assets + private R2 model

This page explains when to use each.

1) Use Cloudflare Pages for simple public JSON hosting

If your API is fully public and you just want to host generated JSON, the simplest path is:

1. run the regular CLI
2. publish the generated output

Example build:

pnpm build

If your output is api-out/, you can publish that through your preferred static-hosting flow.

Cloudflare Pages is a reasonable fit when:

• the API is public
• the output is relatively small
• you do not need authenticated private routes
• you do not need runtime rebuild webhooks

Cloudflare Pages docs:

• Pages limits

2) Use the Cloudflare adapter for mixed public/private APIs

Use the cloudflare-adapter template when you need:

• public routes served as Static Assets
• private routes behind a Worker
• private runtime rebuilds by HTTP POST
• a Cloudflare-aware local preview/dev flow

That flow is documented in:

• Cloudflare Worker + Static Assets Adapter

Current adapter model

• public routes
  • emitted under /public/...
  • served from Cloudflare Static Assets
• private routes
  • remain on original route paths
  • stored in a private R2 bucket
  • served through the Worker
• manifests
  • public manifest under /public/_manifest...
  • private manifest at /_manifest

Important limitation

Public routes are not runtime-refreshable by webhook in this version.

So:

• private routes can be rebuilt by webhook
• public routes require a new build + deploy

Pricing summary for the adapter path

The adapter uses:

• Workers
• Static Assets
• Workers KV
• R2

The key economic behavior is:

• public Static Asset requests are the cheapest path because Cloudflare documents them as free and unlimited when they do not invoke the Worker
• private reads and rebuilds use Worker quota
• private payload storage and reads/writes use R2
• manifest/control-plane usage uses KV

Cloudflare docs:

• Workers pricing
• Workers limits
• Static Assets billing and limitations
• Workers KV pricing
• R2 pricing

If cost clarity matters for your deployment, read the full breakdown in:

• Cloudflare Worker + Static Assets Adapter

Simple rule of thumb:

• mostly public traffic
  • the adapter stays relatively cost-friendly because Static Asset requests are free
• mostly private traffic or rebuild-heavy automation
  • Worker, KV, and R2 usage become the important meters to watch

3) Which option should you choose?

Choose simple static hosting when:

• everything is public
• you only need deployment-time updates
• you do not need Worker auth or runtime rebuilds

Choose the adapter when:

• you need both public and private routes
• you need authenticated private reads
• you need webhook-triggered private rebuilds
• you want the Cloudflare preview/dev workflow
• you are comfortable with public routes requiring build + deploy instead of runtime webhook refresh

4) Deploying a scaffolded Cloudflare project

Typical scaffolded deploy flow:

pnpm build
pnpm deploy

That assumes:

• wrangler.toml is filled in correctly
• the private R2 bucket already exists
• the KV namespace already exists
• your deploy token has the correct Cloudflare permissions

The deployed Worker secrets still need to be set separately in Cloudflare:

• STATIK_BUILD_TOKEN
• STATIK_PRIVATE_AUTH_HEADER_NAME
• STATIK_PRIVATE_AUTH_HEADER_VALUE

Use the dashboard secrets UI or Wrangler:

wrangler secret put STATIK_BUILD_TOKEN
wrangler secret put STATIK_PRIVATE_AUTH_HEADER_NAME
wrangler secret put STATIK_PRIVATE_AUTH_HEADER_VALUE

If you need to seed private outputs after deploy, do it manually with any HTTP client against your deployed Worker:

curl -X POST "YOUR_WORKER_URL/" \
  -H "Authorization: Bearer YOUR_STATIK_BUILD_TOKEN"

Use STATIK_BUILD_TOKEN for that POST request. STATIK_PRIVATE_AUTH_HEADER_NAME and STATIK_PRIVATE_AUTH_HEADER_VALUE are for private reads, not for the seed POST. Make sure the deployed Worker has the same secrets as your local .dev.vars by setting STATIK_BUILD_TOKEN, STATIK_PRIVATE_AUTH_HEADER_NAME, and STATIK_PRIVATE_AUTH_HEADER_VALUE in Wrangler or the Cloudflare dashboard.

Git-connected deployments

Cloudflare also supports deploying a Worker from a connected Git repository. That is a valid deployment shape for this adapter, as long as you keep the same split between deployment credentials and runtime secrets.

Recommended setup:

1. Connect the repository in the Cloudflare dashboard.
2. Choose the branch you want Cloudflare to deploy.
3. Use pnpm deploy as the deployment command if you want the wrapper's build-first behavior.
4. Set the Cloudflare deploy credential and any build-time values in the Git-connected deployment environment.
5. Set the deployed Worker secrets separately for:
   • STATIK_BUILD_TOKEN
   • STATIK_PRIVATE_AUTH_HEADER_NAME
   • STATIK_PRIVATE_AUTH_HEADER_VALUE

If you prefer not to use the wrapper in Cloudflare's build pipeline, you can use wrangler deploy directly and run pnpm build or another build step separately. In that case, keep the same manual private seeding instructions in your runbook.

For custom domains, Cloudflare's recommended path is a Worker Custom Domain:

• Workers Custom Domains

Typical dashboard path:

1. Deploy the Worker.
2. Open Workers & Pages.
3. Select the Worker.
4. Go to Settings -> Domains & Routes.
5. Add a Custom Domain such as api.example.com.

5) Relevant Cloudflare docs

For the adapter path, these official docs are the ones you will use most:

• Create API token
• API token permissions reference
• Find account and zone IDs
• Workers Static Assets overview
• Static Assets configuration and bindings
• Wrangler configuration reference
• Create new R2 buckets
• KV namespaces