Workers Static Assets vs. Cloudflare Pages: Which Should You Choose?

You have a website ready to publish: some pages, stylesheets, JavaScript, and images. Perhaps you also need a login flow or an API. Cloudflare offers two closely related ways to host it: Workers Static Assets and Cloudflare Pages.

Both serve websites through Cloudflare’s global network, and both can run server-side code. The real difference is how they organize your application—and how you build, deploy, and extend it.

Workers Static Assets makes your website part of a Worker application. Pages makes your application part of a site-oriented deployment workflow.

Cloudflare recommends Workers for new projects, while Pages remains supported. That is a useful starting point, but understanding the architecture will help you choose for the right reasons.

Start With the Shared Foundation

A static asset is a file that can be delivered without generating its contents for each request: an HTML page, a stylesheet, a JavaScript bundle, or an image.

“Static” does not mean uninteractive. A browser can download static JavaScript and use it to power a sophisticated interface. The distinction is what the server does: deliver an existing file, or execute code to produce a response.

Both products can combine these two kinds of work:

• Static delivery: return a file such as /images/logo.svg.
• Dynamic execution: run code to handle a request such as /api/orders.

A Worker is server-side code running in Cloudflare’s managed execution environment, called the Workers runtime. You do not manage a conventional server yourself. Pages adds dynamic behavior through Pages Functions, which run on that same runtime.

These are therefore alternatives for many projects—not two layers you normally need to stack together.

Workers Static Assets: One Application, Files and Code Together

How the architecture works

With Workers Static Assets, you configure a directory containing the files you want to publish, often named dist/ or public/. Deployment uploads those files alongside your Worker script, if you have one.

You do not need to write a Worker script just to host static files.

Cloudflare serves the uploaded files through its network and caches them, keeping copies available for efficient delivery. In the default asset-first model:

1. A request arrives.
2. If it matches a deployed asset, Cloudflare serves that file without executing your Worker.
3. If there is no matching asset, the request can reach your Worker, subject to the configured routing and fallback behavior.

That lets one deployment contain both a frontend—the part running in your visitor’s browser—and a backend, the code handling server-side tasks.

Your code can also retrieve a deployed file through an assets binding, commonly named ASSETS. A binding is a configured connection that gives your code access to a resource without requiring you to construct an ordinary public HTTP request to it.

See Cloudflare’s Static Assets overview for the deployment model.

Deciding whether files or code come first

Sometimes you need code to run before a file is returned. For example, you might want to check whether someone is signed in before delivering a private document.

The assets.run_worker_first setting lets you put the Worker first for all requests or selected paths. Your Worker can inspect the request and then retrieve the asset if access is allowed.

This creates an important trade-off:

• Assets first: direct file requests avoid Worker execution.
• Worker first: your code can authenticate, log, or otherwise process the request before serving the file, but each such request invokes the Worker.

If a file requires authorization, make sure its request passes through authorization code. Merely deploying a Worker alongside the file does not protect it.

Direct static-asset requests are free and unlimited under Cloudflare’s documented model. Worker-first requests count toward Worker usage and are subject to the applicable limits and pricing.

There can also be a latency trade-off. Smart Placement, a feature that chooses where Worker code runs to improve access to backend services, can add delay to asset delivery when those requests must travel through the Worker first. The billing and limitations documentation explains these distinctions.

What you can build

Workers Static Assets supports several application styles:

• Static sites: prebuilt pages delivered as files.
• Static-site-generated sites: pages produced ahead of time by a build tool.
• Single-page applications, or SPAs: sites where browser-side JavaScript handles navigation and updates the interface.
• Full-stack applications: a frontend combined with server-side APIs or other backend logic.
• Server-side rendering: generating page HTML on the server when a request arrives, using suitable application code or framework support.

For an SPA, you can configure a fallback to index.html so browser-managed routes work when opened directly. For other sites, a custom 404 response—the standard “not found” response—may be more appropriate. Unknown URLs should not automatically be treated the same way for every application.

You also get support for custom response headers, redirects, and preview URLs. Because this is a Worker application, you can use broader Workers capabilities, including:

• Cron Triggers: run code on a schedule.
• Queue consumers: process messages from a queue, often for background work.

Workers is not missing automated deployments either; it has build and repository integration capabilities. The distinction is that its workflow is not identical to Pages’ branch-oriented controls.

Limits worth knowing

One Worker can have one configured collection of static assets. That collection can contain many files and subdirectories; it is not limited to a single page.

The documented asset limits are:

A MiB, or mebibyte, is approximately 1.05 decimal megabytes. Large downloads generally call for separate storage, such as Cloudflare R2, an object-storage service designed to hold files as individually addressable objects.

Workers also does not natively reproduce Pages’ /functions file-based routing convention. You handle routing in your application code or through a framework. Check the current Workers limits before planning around these numbers.

Cloudflare Pages: A Site-Centered Publishing Workflow

How the architecture works

Pages takes a build-output directory—the finished HTML, CSS, JavaScript, and images produced by your tools—and publishes it as a website.

You can:

• Connect a GitHub or GitLab repository so code changes trigger builds and deployments.
• Use Direct Upload to publish files you have already built.

With Git integration, Pages distinguishes between production deployments and previews associated with branches or pull requests. A branch is a separate line of development; a pull request proposes changes for review. Preview deployments let you inspect those changes as a working website before publishing them to your main audience.

This workflow makes Pages particularly comfortable for documentation and marketing teams that spend much of their time reviewing and publishing site changes.

Adding dynamic behavior with Pages Functions

Pages is not restricted to static websites. Pages Functions let you add server-side code using the Workers runtime.

The conventional setup uses file-based routing: where you place a code file determines the URL it handles. For example:

functions/users/[user].js

can handle a route such as /users/alex, with the bracketed portion representing a variable value.

Functions can connect through bindings to services such as D1, Cloudflare’s managed SQL database, and R2. You can therefore add a contact form, database-backed endpoint, or selected dynamic page without moving the website to a different hosting product.

The important routing control is _routes.json, which determines which requests invoke Functions. Avoid unintentionally sending every stylesheet and image through server-side code: Function requests count toward Workers usage, unlike direct static-file delivery.

Cloudflare documents this behavior in its Pages Functions routing guide.

Limits and workflow constraints

Pages is convenient, but its application model is narrower than Workers:

• A Pages project cannot directly act as a Cron Trigger or queue consumer.
• Workers offers more comprehensive logging options.
• Some deployment choices require planning: a Direct Upload project cannot simply be converted into a Git-integrated project later.

On the Pages Free plan, the documented limits include:

Higher file-count limits are available on paid plans with the documented configuration. Build limits concern producing your deployment, not the number of visitors reading the resulting static pages. Consult the Pages limits for current details.

Which Fits Your Project?

The choice is less about whether your site is “static” and more about which application and deployment model you want.

Pages retains specific advantages, including more granular branch-deployment controls and support for custom domains whose DNS is managed outside Cloudflare. Those details can matter more than the broad architectural preference. Cloudflare’s migration guide and feature comparison is useful even if you are choosing rather than migrating.

The Decision That Matters in Either Product

For a new project, evaluate Workers Static Assets first. It can start as simple file hosting and grow into a more capable application without changing the basic deployment model.

Choose or retain Pages when its publishing workflow meets a specific need.

Whichever you select, sketch your request paths before deploying:

1. Which URLs should serve public files directly?
2. Which require authentication or other server-side logic?
3. What should happen when no file or application route matches?
4. Which requests will execute code and consume runtime usage?

That small routing exercise often matters more than the product name. It determines what your application does, how quickly it responds, and when serving a file becomes running code.