Cloudflare Pages vs Workers: when to use each and how to scale

In 2022 the answer was easy: if your site was static, Pages. If you had server logic, Workers. But in 2026 that line has blurred to the point where the wrong call costs you weeks of tech debt. This is the guide I wish I'd had before starting to migrate Agentikas.

What Pages and Workers actually are

Cloudflare Workers is the original product: a serverless platform where you ship a JavaScript script and it runs at the edge. Every request goes through your code. You can do anything — render HTML, process forms, hit APIs, mutate headers. Pure infrastructure.

Cloudflare Pages came later as an opinionated layer on top. Pages is built for frontend apps: Git integration, per-PR preview deploys, global asset hosting, and optionally a Worker behind it for dynamic bits. If your site is static React, push the build and you're done. If you need some logic, Pages injects a Worker behind it.

For years the distinction was clean:

• Static sites → Pages
• APIs and complex logic → Workers

But with Next.js stepping in — a framework mixing static, SSR and edge in one app — the choice got subtler.

What they share

Both run on the same Cloudflare edge network (275+ locations). Both have generous free tiers (100K requests/day on Workers, unlimited invocations on Pages). Both support nodejs_compat, fetch API, and the same basic primitives. If your only question is "can I run code on Cloudflare's edge?", the answer is yes on both.

The difference is the mental model and, crucially, the tooling around them.

Where they diverge

Size limits

• Pages: 25 MB per compressed file, no overall limit.
• Workers (free): 3 MB compressed, 10 MB uncompressed.
• Workers (paid, $5/mo): 10 MB compressed.

For a mid-size Next.js app this usually isn't an issue — worker bundles tend to be ~1 MB. But if you import heavy libraries (AWS S3 SDK alone is 3 MB, Puppeteer is in another universe), the difference matters.

Deploy model

Pages has native Git integration. Connect your GitHub repo and every push deploys automatically. Branches generate preview URLs. It's Cloudflare's Vercel experience.

Workers traditionally deployed via wrangler deploy from your terminal or CI. There was no official Git integration until Cloudflare added it recently in beta. If you want push-to-deploy, set up GitHub Actions.

This operational detail kills more projects than you'd think. If your team expects auto-deploys, Pages saves you an afternoon of setup.

Next.js adapters

Here's the real drama.

For Pages: @cloudflare/next-on-pages. A wrapper around vercel build that converts Next.js's output to the format Pages expects. Worked well for two years, now in maintenance mode. Doesn't support modern Next.js features (ISR, Cache Components, frictionless streaming) and breaks in subtle combinations with monorepos and Turbopack.

For Workers: @opennextjs/cloudflare. The modern adapter, built by OpenNext — the project that launched the standard for Next.js adapters outside Vercel. Supports every modern feature, and as of March 2026 it's the path officially recommended by the Next.js team itself for deploying to Cloudflare.

The Next.js 16.2 Adapter API made it clear: the future is Workers + OpenNext. Cloudflare is building its own official adapter on top of OpenNext, shipping during 2026.

Translated: if you start a new Next.js project on Cloudflare today, go straight to Workers + OpenNext. If you're already on Pages, migrating soon saves pain.

Debugging runtime errors

Probably the biggest practical difference. On Pages, when something fails in the associated Worker, logs surface in the Cloudflare Dashboard with some delay and limited metadata. On Workers, wrangler tail gives you real-time streaming of every request with full request/response and stack traces.

When you're debugging a mysterious 500, that difference decides whether you spend 10 minutes or 3 hours.

The 2026 decision

Stay on Pages if...

• Your app is mostly static (landing, portfolio, simple blog)
• You don't mind being on an adapter without a future
• You need Git auto-deploy now
• It's working and you don't want to touch it

Move to Workers if...

• You use Next.js 15+ with modern features (Server Actions, ISR, streaming, Cache Components)
• You have or will have a monorepo with shared packages
• You need decent debugging (wrangler tail is gold)
• You want to align with the official future of Next.js on Cloudflare

Neither product is dead — Cloudflare keeps supporting Pages and will. But the money and the attention are moving to Workers.

Scaling Workers: from one to many

Once you pick Workers as the platform, the next problem hits: your project grows. What started as one Next.js app becomes three — a landing, a platform, a CMS. You share components, queries, and utilities, and discover the same code copied in multiple places.

The solution is a monorepo. The practical rule we apply: npm workspaces first (zero setup, solves 80%), Turborepo the day the build hurts (not before), Nx only for large teams. There's a separate post on this blog deep-diving the three tools if you want the detail.

The immediate future

The work of Next.js's Adapters group is going to reshape the landscape over the next few months. Cloudflare is building its own official adapter on top of OpenNext. Netlify and AWS are doing the same. All will consume the same stable Next.js 16.2 Adapter API.

What that means for you:

• Code you write today with OpenNext will survive that transition. Cloudflare's official adapter will be compatible.
• Feature parity across platforms will be much greater. Until now, a Next.js feature could take months to land on Cloudflare if it landed at all. With the Adapter API, it lands the same on all.
• Platform-specific bugs will shrink. When every adapter passes the same test suite, the quirks disappear.

In short: 2026 is the year Next.js on Cloudflare becomes a first-class product, not an alternative deploy with asterisks.

What I take away

After migrating Agentikas from Pages to Workers + OpenNext, three lessons:

1. Pick the future adapter, not the one you already know. The cost of switching later is greater than learning the new one now.
2. Don't over-engineer the infrastructure. npm workspaces solves 80% of the value. Turborepo is useful when builds hurt. Nx is for big teams.
3. Document the gotchas. Things that took you hours to find — compatibility_date, transpilePackages, hoisting — aren't in the official docs. Write them up for whoever comes next.

If you're starting a Next.js on Cloudflare today: Workers + OpenNext + npm workspaces. No Pages, no Turborepo yet, no Nx. You move fast and your code is compatible with the official future of the ecosystem. The day builds get too slow, you add Turborepo. That day isn't today.

---

At Agentikas we build infrastructure for the agentic web. Our blog is open source and the migration code I describe lives in github.com/agentikas/agentikas-blog.