skip to content

In Cloudflare Workers, how do Previews, Version URLs and Wrangler environments differ when a team wants to test a pull request before production?

level: middleimportance: should knowfreq 30%

answer

  1. branch copy versus one version
  2. which resources each one touches
  3. previews block, not inherited
  4. preview_urls still names Version URLs

basics

~20 s

Previews from wrangler preview are per-branch copies with their own bindings and are meant for pull requests. Version URLs run one uploaded version against production resources. Wrangler environments are separately named, long-lived Workers such as a staging stage.

solid answer

~40 s

A **Version URL**, printed by `wrangler versions upload`, runs one version at `<8-character version prefix>-<worker>.<subdomain>.workers.dev` with that version's **production** bindings, so it suits a last check before `wrangler versions deploy`, not PR testing. `--preview-alias` gives it a stable name, and the config key is still `preview_urls`. A **Preview**, from `wrangler preview` (Wrangler 4.135.0+), is a branch copy under the same Worker that does not inherit production settings: it takes vars and bindings from the `previews` block, gets its own Durable Object namespace automatically, and isolates KV, D1 or R2 only if bound to different resources. A **Wrangler environment** (`wrangler deploy --env staging`) is a separate Worker for a persistent stage.

go deeper

for a junior

Remember that wrangler preview is for branches and wrangler versions upload gives a URL for one version, and that the second one uses production data.

for a middle

Explain which resources each mechanism touches: the previews block, automatic Durable Object isolation, and that KV, D1 and R2 need separate bindings.

for a senior

Show the failure cases: PR traffic writing production rows through a Version URL, Durable Object Workers having no Version URLs, and Preview service bindings calling production.

for a principal

Decide the team's convention: Previews per pull request, one persistent staging environment or both, and how preview resources and Access protection are provisioned.

## Three ways to run code that is not yet production Cloudflare Workers offers three different mechanisms that all sound like "a preview", and teams often pick the wrong one for pull request testing. They differ in **what they run**, **which resources they touch** and **how long they live**. | | Previews | Version URLs | Wrangler environments | |---|---|---|---| | Command | `wrangler preview` | `wrangler versions upload` | `wrangler deploy --env staging` | | What it is | A branch copy under the same Worker | One uploaded version of the Worker | A separately named Worker | | Resources | Its own settings from the `previews` block | Production bindings of that version | Whatever the environment block binds | | URL | `<preview-name>-<worker>.<subdomain>.workers.dev` | `<first 8 characters of version ID>-<worker>.<subdomain>.workers.dev` | The environment Worker's own routes | | Best for | Branches and pull requests | Inspecting one version before a deploy | Long-lived staging or development | ## Version URLs: one version, production resources Every new version can get a **Version URL** on `workers.dev`; `wrangler versions upload` prints it. These were previously called preview URLs, and the Wrangler config key that turns them on or off is still `preview_urls`. When no Version URL setting exists yet, Version URLs follow the `workers_dev` setting: enabled if `workers_dev` is enabled, disabled if not. Omitting `preview_urls` leaves an existing setting unchanged. The important property: a Version URL runs that version **with the production resources configured for it**. A request to a Version URL reads and writes the production D1 database, KV namespace and R2 bucket. That is fine for checking one release candidate just before `wrangler versions deploy`, and it is exactly what Cloudflare's docs warn against for branch or pull request testing. Other details worth knowing: - An **alias** gives a stable name: `wrangler versions upload --preview-alias staging` serves that version at `staging-<worker>.<subdomain>.workers.dev`. Aliases can be created only during upload, must use lowercase letters, digits and dashes and start with a letter, and alias plus Worker name must fit a 63-character DNS label. Only the 1000 most recently deployed aliases are kept. - Version URLs are **public** unless you protect them with Cloudflare Access. - They are **not generated for Workers that implement a Durable Object**, including Containers and Sandbox Workers. - Requests to a Version URL do not appear in Workers Logs, `wrangler tail` or Logpush. ## Previews: per-branch copies with their own settings **Previews** are the recommended way to test a branch. `wrangler preview` (Wrangler 4.135.0 or later) creates or updates a Preview named after the current Git branch, or the name given with `--name`, under the same Worker. Each Preview gets a **Preview URL** that always serves its latest deployment and a **Deployment URL** for each individual deploy. Previews **do not inherit production settings**. Their variables and bindings come from the `previews` block of the Wrangler file, and secrets are set with `wrangler preview secret put`. Isolation depends on the resource: 1. A Durable Object class defined in the same Worker gets a **new namespace and storage per Preview** automatically, and Containers get their own instances. 2. KV, D1, R2 and queue producers are isolated **only if the `previews` block binds them to a different resource**; two Previews bound to the same D1 `database_id` share rows. 3. Service bindings from a Preview call the bound Worker's **production** deployment, Workflow bindings use the existing Workflows, routes and Cron Triggers target production, and queue consumers cannot target a Preview. Limits: 100 Previews per Worker on the Free plan and 500 on paid plans, each keeping up to 100 deployments; the oldest is deleted when a limit is reached. Delete one with `wrangler preview delete --name <preview-name>`. ## Wrangler environments: separate Workers An environment defined under `env.staging` in the Wrangler file is deployed with `--env staging` as a **separately named Worker**, such as `orders-api-staging`. It is persistent, has its own routes and bindings, and is the right fit for a long-lived staging stage. A `previews` block can sit inside an environment, and `wrangler preview --env staging` then creates branch Previews under the staging Worker. Every Preview command must repeat the same `--env`, or Wrangler targets the top-level Worker. ## Workers Builds With Cloudflare's Git integration, commits on the **production branch** run the deploy command (by default `npx wrangler deploy`). When preview builds are enabled, other branches run the **Preview command**, which defaults to `npx wrangler preview` for new projects. Changing that command to `npx wrangler versions upload` produces Version URLs instead, with the production-resource caveat above. ## The interview answer in one line Use Previews for pull requests, Version URLs to inspect one release candidate, and environments for long-lived stages, and check which resources each one binds before letting it write data.

  • A Preview for a feature branch wrote test rows into the production D1 database. How did that happen?
    Previews isolate a D1 database only when the `previews` block binds it to a different `database_id`. If the Preview was bound to the production database ID, it shares production rows. Durable Objects are the exception that is isolated automatically; KV, D1, R2 and queues need a separate resource in the `previews` block.
  • Why might wrangler versions upload print no Version URL for a Worker?
    Version URLs may be disabled: when no Version URL setting exists they follow `workers_dev`, so a Worker with `workers_dev` off has them off unless `preview_urls` is set to true. They are also never generated for a Worker that implements a Durable Object class, including Containers Workers.

  • A Version URL runs against isolated copies of the Worker's databases.
  • Previews inherit production variables and bindings unless you override them.
  • An aliased Version URL is a branch preview with its own resources.
  • Version URL requests show up in wrangler tail like production traffic.
  • Every Preview gets its own KV namespace and D1 database automatically.

Assumes Wrangler 4.149.0; Previews and wrangler preview need Wrangler 4.135.0 or later, and Version URLs were formerly called preview URLs.