KahWee

Thoughts on web development, programming, and technology

Migrating from Cloudflare Pages to Workers - Do You Even Need To?

Cloudflare is consolidating Pages into Workers. The migration is a one-line config change for static sites, but the real question is whether you need to migrate at all.

The Cost Reality

Static hosting is free on both platforms. The number of pages doesn't matter.

Pages charges for builds:

  • Free: 500 builds/month
  • Pro: $20/month for 5,000 builds

Workers charges for server-side execution:

  • Free: 100,000 requests/day
  • Paid: $5/month for 10M requests

For a static blog: Both are $0/month unless you exceed 500 builds monthly or add dynamic features. I've been on the free tier for years.

The Migration: Literally One Line

Pages runs on Workers infrastructure. The migration is changing one property in your config:

- pages_build_output_dir: "./dist"
+ assets:
+   directory: "./dist"

Then redeploy. That's it.

Full steps:

  1. Install Wrangler: bun install -D wrangler@latest
  2. Update your config (see above)
  3. Configure API token permissions (see below)
  4. Deploy: bunx wrangler deploy

The official migration guide has more for complex setups with Functions, but most static sites won't need it.

API Token Permissions

If you're using an API token for deployment (recommended for CI/CD), you'll need these permissions:

Required permissions:

  • Account → Cloudflare Pages → Edit (for Pages deployments)
  • Account → Workers Scripts → Edit (for Workers deployments)
  • Account → Account Settings → Read (for account info)

Optional but recommended:

  • Zone → Workers Routes → Edit (if using custom domains with your zone)

Setting up the token:

  1. Go to Cloudflare Dashboard → API Tokens
  2. Click "Create Token"
  3. Add the permissions above
  4. For Zone permissions, select "Specific zone" and choose your domain (e.g., kahwee.com)
  5. Save the token and use it in your CLOUDFLARE_API_TOKEN environment variable

What Workers Actually Adds

Workers offers capabilities Pages doesn't:

Node.js API compatibility:

  • crypto, tls, net, dns modules
  • Better support for frameworks expecting Node APIs

Edge compute features:

  • Durable Objects (real-time collaboration, WebSocket state)
  • Cron Triggers (scheduled tasks at the edge)
  • Queue Consumers (background job processing)
  • Gradual Deployments (progressive rollouts)

Better observability:

  • Workers Logs with request-level detail
  • Logpush for analytics pipelines
  • Source Maps for debugging

Do You Need This for a Blog?

Honest answer: probably not.

If you're serving pre-built HTML, CSS, and JavaScript, both platforms are free and fast. The migration is trivial, but what do you actually gain?

What Actually Matters for Blogs

Form handling:
Contact forms, newsletter signups, comment APIs. This is the main reason to migrate—you can handle form posts without a separate backend service.

API endpoints:
Search, view counts, reading time tracking. Workers lets you build lightweight APIs alongside your blog without spinning up a server.

Dynamic content:
Personalized content, A/B testing, geo-redirects. Useful if you're experimenting with edge-rendered content, but overkill for most blogs.

What You Don't Need

Durable Objects:
Real-time collaboration, WebSocket connections, stateful applications. Unless you're building live comments or a collaborative editor, skip it.

Cron Triggers:
Scheduled tasks. Maybe useful for automated post publishing, but most static site generators handle this at build time.

Queue Consumers:
Background job processing. Way beyond what a typical blog needs.

When the Migration Makes Sense

Migrate if:

  • You're planning to add comments, search, or dynamic features
  • You want lightweight APIs for your blog (likes, subscriptions, view counts)
  • You're experimenting with edge-rendered content or personalization
  • You need better observability than Pages offers

Stay on Pages if:

  • Your blog is purely static and will stay that way
  • You don't need any Workers-only features
  • The Pages workflow works fine for you

My Take

I migrated because I wanted to handle newsletter signups without third-party services. The migration took 5 minutes—most of it was waiting for deployment.

But if you're just serving markdown-to-HTML, don't bother. Pages works great for static sites. The migration is simple enough that you can do it anytime if you need Workers features later.

All Tags