Static sites on Cloudflare Workers

From Astro to Workers static assets: the real commands, a comparison of three deploy targets, and five mistakes.

Cover image illustrating static site deploys on Cloudflare Workers
Cover image illustrating static site deploys on Cloudflare Workers

Static sites on Cloudflare Workers

This is a record of what I actually did to put an Astro blog on Workers, including the commands and the mistakes. It assumes you already have a Cloudflare account and a domain pointed at it.

Setup

I use Node 20, Astro 5 and Wrangler 4. No Docker, no VPS. All of the infrastructure lives in one Cloudflare account, and the free plan is enough for a personal blog.

# scaffold a new Astro project, pick "Empty" when prompted
npm create astro@latest notice-web
cd notice-web

# add Wrangler for static asset deploys
npm install --save-dev wrangler@4
npx wrangler login

After logging in, Wrangler stores a token on disk. On CI, use CLOUDFLARE_API_TOKEN instead of the interactive login.

Repository layout

Everything lives in one repo with two folders:

vistaverde_autopost/
├── cms/                # SonicJS: writing API, D1, R2
│   ├── src/
│   └── wrangler.toml
├── web/                # Astro: static build
│   ├── src/pages/
│   └── wrangler.toml
└── .secrets/           # never committed

Splitting by role gives each side its own wrangler.toml and its own deploy. The CMS deploys when the schema changes, the site deploys when content changes. The two pipelines never step on each other.

Build and deploy

Astro builds into dist/ by default. With Workers static assets you point Wrangler at that folder:

# web/wrangler.toml
name = "notice-web"
compatibility_date = "2026-01-15"

[assets]
directory = "./dist"
not_found_handling = "404-page"

And these are the real commands I run:

cd web
npm run build          # astro build → dist/
npx wrangler deploy    # upload dist/ + asset manifest

The first deploy takes about 40 seconds because every image gets uploaded. Later deploys only upload changed files, usually under 10 seconds. If every deploy takes 40 seconds, check whether assets.directory points somewhere that forces Wrangler to re-hash everything.

Fetching content at build time

The site does not call the API when a reader arrives. It calls once, at build time:

// web/src/lib/posts.ts
const CMS = import.meta.env.PUBLIC_CMS_URL ?? 'https://cms.vistaverde.top';

export async function getPosts() {
  const res = await fetch(`${CMS}/api/post?limit=100`);
  if (!res.ok) throw new Error(`CMS responded ${res.status}`);
  const { data } = await res.json();
  return data.filter((p: any) => p.status === 'published');
}

One thing to remember: /api/post only returns published posts, so the filter above is belt and braces. Drafts never leak into the public build, which is the behaviour you want.

Comparing the options

I ran all three setups within the same month. The numbers below are from roughly 500 page views a day.

Criterion Workers static assets Cloudflare Pages VPS + Nginx
Cost/month $0 $0 ~$5
Deploy time 8–40 s 30–90 s 1–3 min
Configuration one TOML file dashboard + git systemd, TLS, firewall
Edge cache built in built in build it yourself
Rollback wrangler rollback pick a deployment write a script
Best for blogs, docs, landings complex build pipelines apps with background work

For a blog that is only HTML and images, the first column is the least work. I still keep a VPS for other things, but the blog no longer lives there.

If you have to SSH into a server to fix a post, your architecture is wrong. Content should travel through an API or git, not through a terminal.

Common mistakes

Here is the list I wish someone had handed me first:

  1. Missing compatibility_date. Wrangler warns, then deploys anyway. Pin a date and bump it quarterly.
  2. Over-caching the API. A five-minute cache means five minutes between saving and seeing. Notice uses a 5-second TTL for the API and permanent caching for static files.
  3. Duplicate slugs. The API returns 409 when a slug already exists. My seed script stores document ids in a state file so a re-run updates instead of creating again.
  4. Wrong MIME type on upload. R2 does not guess. Send text/markdown for .md files, or browsers will download rather than display them.
  5. Forgetting the draft. Drafts are absent from the public list by design. To preview one you must call /api/post/:id with an admin token, or build a preview route.

A small note on images

Covers are 1200×630 SVGs under 4 KB. Being SVG, they stay sharp at any size and need no resize pipeline. The downside is that some platforms reject SVG for og:image, so I export a PNG when a post needs to be shared.

# quick sanity check after a deploy
curl -sI https://notice.vistaverde.top/ | head -5

You want HTTP/2 200 with cf-cache-status: HIT on the second request. If it is always MISS, inspect the asset's Cache-Control header.

Wrap-up

The whole system, CMS included, took about two evenings. The hard part was not deploying it, but keeping the content good enough to deserve a deploy. The next post is about that: how I draft with AI while keeping my own voice.

References