Pages or Workers? Choosing the right compute model

After this lesson you'll be able to pick between Cloudflare Pages and a plain Worker for a new project, justify the choice from Cloudflare's own guidance, and restructure the same app either way.

Cloudflare Pages and Cloudflare Workers used to be two separate products: Pages for git-connected static/full-stack sites, Workers for programmable edge functions. That line has mostly disappeared. Workers can now serve static assets directly (an assets binding, no separate product needed), which means a plain Worker can do almost everything Pages does. Pages hasn't gone away and isn't deprecated — but for a brand-new project, Cloudflare's own docs now point most people toward Workers first. This lesson is about knowing why, and knowing the cases where Pages still wins.

What each one actually is

Pages is a deploy target built around git: connect a GitHub/GitLab repo, Cloudflare builds it on every push, and you get a production deployment plus a unique preview URL for every branch and pull request automatically. Dynamic behavior comes from Pages Functions — files under a functions/ directory that map to routes, running on the Workers runtime underneath.

A plain Worker is a single script (or module) you deploy with Wrangler. It has full programmatic control over routing, and since the introduction of the assets binding it can also serve a directory of static files — configured in wrangler.jsonc — with the option to run your own code first, fall back to your own code when no asset matches, or serve assets straight from cache with no Worker invocation at all.

How they actually differ now

Both platforms run on the same underlying Workers runtime and both can serve a static frontend plus a dynamic API. The differences that remain are concrete, not philosophical:

• Git integration and preview deployments — a Pages strength, but not exclusive to Pages anymore. Pages was built around this from day one: push a branch, get a preview URL, merge to deploy. Workers Builds now brings the same idea to plain Workers — connect a repo, get automatic builds on push and preview deployments for branches — but it's a newer, separately-configured feature rather than the default deploy path the way it is on Pages.
• Feature surface — a Workers strength. Cloudflare's migration docs state plainly that "Workers has a distinctly broader set of features available to it, including Durable Objects, Cron Triggers, and more comprehensive Observability." Pages Functions cannot use Cron Triggers, Logpush, Tail Workers, Queues consumers, Rate Limiting, or Email Workers bindings, and only get Durable Objects access indirectly. If your app needs any of these, you're choosing a plain Worker or you're routing that piece of work to a separate Worker anyway.
• Routing control — a Workers strength. A Worker's run_worker_first and not_found_handling options give you fine-grained control over exactly when your code runs versus when the platform serves an asset directly. Pages Functions' routing model (file-based, under functions/) is simpler but less flexible — e.g. Pages cannot serve assets scoped to specific paths the way a Worker's assets config can.
• Deploy model. Pages deploys are inherently git-triggered. A plain Worker's default deploy is wrangler deploy from your machine or CI — git integration via Workers Builds is opt-in, not the default mental model.

What Cloudflare actually recommends

There is no blanket "Pages is deprecated, migrate now" statement in Cloudflare's docs — treat any claim to the contrary as a misreading. What the docs do say, concretely:

• Existing Pages projects continue to be supported. Nothing forces a migration.
• Cloudflare's Workers static-assets migration guide describes moving from Pages to Workers as "often a straightforward process," and exists specifically to help teams move when they need a feature Pages doesn't have.
• For projects starting today, Workers with static assets is the path Cloudflare steers new users toward in its current onboarding, precisely because it has the superset of features — you're not closing off Durable Objects, Cron Triggers, or advanced routing later just because your app starts out as "mostly static."

In practice: pick a plain Worker by default for a new project unless git-native preview-per-PR with zero extra config is the thing you value most, or your team's workflow is already built around Pages' git dashboard.

Worked example: a feedback form with an API

Same small app — a static HTML form plus a /api/feedback endpoint that validates input and writes to storage — structured both ways.

As a Pages project

my-app/
├── public/                  # static assets, deployed as-is
│   ├── index.html
│   └── style.css
└── functions/
    └── api/
        └── feedback.ts       # maps to POST/GET /api/feedback

// functions/api/feedback.ts
interface Env {
  FEEDBACK_DB: D1Database;
}

export const onRequestPost: PagesFunction<Env> = async (context) => {
  const { message, email } = await context.request.json();
  if (!message || typeof message !== "string") {
    return Response.json({ error: "message is required" }, { status: 400 });
  }

  await context.env.FEEDBACK_DB
    .prepare("INSERT INTO feedback (message, email) VALUES (?, ?)")
    .bind(message, email ?? null)
    .run();

  return Response.json({ ok: true });
};

Deploy by connecting the repo in the dashboard (or wrangler pages deploy public); every push to a branch gets its own preview URL with no extra config.

As a plain Worker with an assets binding

my-app/
├── public/                  # static assets, referenced by wrangler config
│   ├── index.html
│   └── style.css
├── src/
│   └── index.ts              # the Worker script — all routing is explicit
└── wrangler.jsonc

// wrangler.jsonc
{
  "name": "feedback-app",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "assets": {
    "directory": "./public",
    "binding": "ASSETS",
    "not_found_handling": "single-page-application"
  },
  "d1_databases": [
    { "binding": "FEEDBACK_DB", "database_name": "feedback", "database_id": "<uuid>" }
  ]
}

// src/index.ts
interface Env {
  ASSETS: Fetcher;
  FEEDBACK_DB: D1Database;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/api/feedback" && request.method === "POST") {
      const { message, email } = await request.json();
      if (!message || typeof message !== "string") {
        return Response.json({ error: "message is required" }, { status: 400 });
      }

      await env.FEEDBACK_DB
        .prepare("INSERT INTO feedback (message, email) VALUES (?, ?)")
        .bind(message, email ?? null)
        .run();

      return Response.json({ ok: true });
    }

    // Not an API route — fall back to serving the static asset.
    return env.ASSETS.fetch(request);
  },
};

The Worker version makes routing explicit in code (you can see exactly when the API branch runs versus when it falls through to assets), and the same script could add a Durable Object, a Cron Trigger, or a Queue consumer without switching platforms. Deploy with wrangler deploy, or connect the same repo via Workers Builds for the equivalent git-push-to-deploy and per-branch preview behavior.

Use cases matrix