Cloudflare Pages vs Workers: When to Use What

If you’ve spent any time on Cloudflare’s platform, you’ve probably asked yourself: should I use Pages or Workers?

The answer used to be simple. Pages was for static sites. Workers was for server-side logic. But Cloudflare has been merging these two products so aggressively that the distinction barely exists anymore — and that’s causing real confusion.

I run both. This site is deployed on Cloudflare Pages with a Workers adapter. I’ve also built standalone Workers for APIs and background tasks. Here’s what I’ve learned about when to reach for each one.

What Pages Actually Is

Cloudflare Pages started as a static hosting platform — think Netlify or Vercel, but on Cloudflare’s edge network. You connect a GitHub repo, push code, and it builds and deploys automatically.

The key features that still make Pages attractive:

Git-integrated deploys — push to main for production, push to any other branch for a preview URL
Preview deployments — every branch gets its own URL automatically (e.g., develop.your-project.pages.dev)
Zero config for static sites — HTML, CSS, JS, images — just works
Free tier is generous — 500 builds per month, unlimited bandwidth

If you’re building a blog, portfolio, docs site, or marketing page, Pages is the obvious choice. You don’t need to think about routing, request handling, or infrastructure.

What Workers Actually Is

Workers is Cloudflare’s serverless compute platform. Your code runs on every request at the edge — no cold starts, no containers, no regions to pick. It’s a V8 isolate that executes JavaScript/TypeScript.

Workers are for:

APIs and server-side logic — REST endpoints, authentication, data processing
Request transformation — modify headers, rewrite URLs, handle redirects
Scheduled tasks — cron triggers for background work
Real-time features — WebSockets via Durable Objects

Workers give you full control over the request/response lifecycle. You’re writing a server, just one that happens to run at the edge.

Where It Gets Confusing

Here’s the thing: Pages can run Workers code.

When you add a functions/ directory to a Pages project, or use a framework adapter (like Astro’s @astrojs/cloudflare), your Pages project gains server-side capabilities. Under the hood, Cloudflare compiles your server routes into a Worker that sits in front of your static assets.

So now you have:

A Pages project that serves static files and runs server logic
A Workers project that can serve static files from R2 and run server logic

They’re converging. Cloudflare even announced they’re unifying Pages and Workers into a single platform.

The Migration Push

If you’ve been paying attention, Cloudflare has been nudging Pages users toward Workers for a while:

The wrangler pages commands now recommend migrating to wrangler deploy
New features land on Workers first
Pages-specific quirks (like the _worker.js convention) are being phased out

This doesn’t mean Pages is dying — it means Pages is becoming Workers with nicer defaults for static-first projects.

My Decision Framework

After running both in production, here’s how I decide:

Use Pages When:

Your project is content-first — blogs, docs, portfolios, marketing sites
You want preview deployments per branch — Pages gives you this for free
You’re using a framework — Astro, Next.js, Nuxt, SvelteKit all have Cloudflare adapters that target Pages
Your team needs simple deploys — connect GitHub, push, done

Use Workers When:

You’re building a pure API — no HTML, no static assets, just JSON
You need Durable Objects — real-time collaboration, WebSockets, stateful logic
You need cron triggers — scheduled background tasks
You’re building middleware — sits in front of other services, transforms requests

Use Both When:

This is actually the most common pattern for real projects. Your frontend lives on Pages (with framework SSR via the Workers adapter), and standalone Workers handle things that don’t belong in your frontend:

A separate Worker for your API
A Worker that processes webhooks
A Worker that runs scheduled cleanup tasks
A Worker that handles email routing

What I’m Running

This site (jjaimealeman.com) is an Astro project deployed to Cloudflare Pages. The Astro Cloudflare adapter compiles my server routes into a Worker automatically. I get:

Static pages pre-rendered at build time (blog posts, project pages)
Server-side routes when I need them (API endpoints, form handling)
D1 database access for dynamic data
R2 storage for images and assets
KV for caching

It’s a Pages project with Worker capabilities. I didn’t have to choose one or the other — I got both.

The Gotchas

A few things I’ve learned the hard way:

1. wrangler.jsonc is picky. Despite the .jsonc extension, Cloudflare’s Pages build parser chokes on trailing commas. Use strict JSON formatting in that file.

2. Bindings must match. If your wrangler.jsonc references a D1 database or KV namespace that doesn’t exist (or was deleted), the deploy will fail silently or throw cryptic errors. Always verify bindings in the Cloudflare dashboard.

3. Preview vs. Production environments. Pages preview deployments share the same bindings as production unless you explicitly configure separate environments. Be careful with database writes on preview branches.

4. NuxtHub is dead. If you’re coming from Nuxt, don’t use @nuxthub/core. NuxtHub Admin was sunset on December 31, 2025. Use direct Cloudflare bindings (D1, KV, R2) via wrangler.jsonc instead.

The Bottom Line

Stop thinking of Pages and Workers as separate products. They’re two entry points into the same platform:

Pages = static-first with optional server capabilities
Workers = server-first with optional static serving

Pick the entry point that matches your project’s center of gravity. If most of your content is pre-rendered with some dynamic sprinkled in, start with Pages. If most of your logic is server-side with some HTML sprinkled in, start with Workers.

And if you’re building something non-trivial, you’ll probably end up using both — and that’s fine. That’s how the platform is designed to work.