Cloudflare Pages Production And Preview Environments

A first-principles map for understanding what is live, what is preview, how environment variables work, and when customers should use separate projects for dev, staging, and production.

1 Code Or Assets

A commit or direct upload creates a built snapshot of HTML, CSS, JS, Functions, and bindings.

2 Pages Deployment

Every deploy gets a unique immutable deployment URL such as hash.project.pages.dev.

3 Environment Label

Cloudflare classifies the deployment as production or preview.[1]

4 Alias Routing

Production aliases like project.pages.dev and custom domains point to the latest production deployment.

5 Customer Testing

Preview URLs let people test a version without moving the production alias.

How To Read A Deployment

Cloudflare Pages deployment lists show whether a deployment belongs to Production or Preview. That label matters more than the presence of a hash URL.

Deployment URL: hash.project.pages.dev
Environment: Production or Preview
Branch: main, staging, feature/x, etc.

A production deployment can still have a hash URL. The normal production alias points to the latest production deployment, while the hash URL points to one exact snapshot.

What Preview Means

A preview deployment is not a separate permanent environment by itself. It is a deployment snapshot marked as preview so teams can inspect it before production changes.

With Git integration, commits to non-production branches can create preview deployments, while the production branch updates production.[1]

main        -> production
feature/x   -> preview
bugfix/y    -> preview

The Trap

There can be many preview deployments, but Cloudflare Pages does not give every preview its own independent named environment configuration.

In Pages configuration, production and preview are the environment scopes. Cloudflare notes that these are the only options and that branch-based configuration is not currently supported.[2]

{
  "env": {
    "production": {},
    "preview": {}
  }
}

Customer Ask

“I want environment variables specific to each preview” is a fair platform ask, but it is not the simple native Pages model.

The native Pages model is better understood as two config buckets: one for production, one shared by previews.

All preview deployments
  use preview vars
  use preview bindings
  do not each get separate vars automatically

Simple Project

  • One Pages project.
  • One production URL.
  • One shared preview configuration.
  • Good for small apps and docs sites.

Customer Environments

  • Separate project for dev.
  • Separate project for staging.
  • Separate project for prod.
  • Each gets its own URL, bindings, secrets, Access policy, and preview deployments.

Branch-Aware Builds

  • Use CF_PAGES_BRANCH in build logic.[3]
  • Useful for build commands and static values.
  • Not a full substitute for independent runtime secrets per preview.
Model How It Works When To Use
One project Production deployments use production config. All preview deployments share preview config. Use when preview is just a review surface and does not need isolated DBs/secrets per branch.
Separate projects app-dev, app-staging, and app-prod are separate Pages projects with separate settings. Use when customers need real environment isolation, formal promotion gates, different Access policies, or different databases.
Custom CI direct upload CI builds with custom variables and uploads the result to the selected project. Use when the team wants full control and accepts more deployment plumbing.

How Many Previews?

Cloudflare lists an unlimited number of active preview deployments for Pages projects.[4]

That does not mean every preview is a fully isolated environment. It means many preview deployment snapshots can exist.

Quota And Cost Shape

Preview deployments are not usually charged as “one environment each”, but they can consume platform limits.

Pages limits include monthly build count, concurrent builds, build timeout, file count, file size, and Function request limits. Pages Functions usage counts toward Workers plan limits.[4]

Memory Line

Preview is a deployment classification, not automatically a full customer environment. For real dev/staging/prod isolation, use separate Pages projects and let each project have its own production URL plus its own previews.

Many previews, two native config scopes

References

  1. Cloudflare Pages preview deployments: explains preview deployments and the relationship between production branches, preview branches, and deployment URLs.
  2. Cloudflare Pages Functions Wrangler configuration: documents production and preview environment configuration and states that these are the only options, with branch-based configuration not currently supported.
  3. Cloudflare Pages build commands per branch: documents using branch information such as CF_PAGES_BRANCH to vary build commands.
  4. Cloudflare Pages limits: lists Pages limits, including preview deployment limits, build limits, file limits, and Pages Functions limits.