A Worker Preview is a named copy of a Worker: own URL, own variables, secrets, and bindings, and isolated same-Worker Durable Object (and Container) state. The parent's live deployment is untouched.
This is the branch and pull-request path. It is not a Worker version. Versions are for gradual rollouts and canaries — see Gradual deployments.
Preview another stage's Worker
const parent = yield* Cloudflare.Worker.ref("Api", { stage: "prod" });
const api = yield* Cloudflare.Worker("Api", {
main: "./src/api.ts",
preview: {
of: parent,
message: `PR #${process.env.PR_NUMBER}`,
},
});
// https://<stage>-<worker>.<account>.workers.dev
api.url; The Preview name defaults to a DNS-safe form of the stack stage
(pr-123, feat-login). Override with preview.name. Destroying
the Preview Worker deletes the Preview; the parent stays up.
Bindings are whatever this Worker declares. Point them at staging
resources, or let a PR stage create its own KV / D1 / R2. Same-Worker
Durable Object classes are
isolated automatically — each Preview gets its own namespace, deleted
with the Preview. Version workers (version.parent) cannot host
Durable Object classes; Previews can.
Custom-domain Preview URLs
Enable Previews on the parent Worker's custom domain:
yield* Cloudflare.Worker("Api", {
main: "./src/api.ts",
domain: {
name: "app.example.com",
previews: true,
},
}); A Preview of that Worker is then at
https://<preview-name>.app.example.com, plus a pinned
https://<deployment-id>-<preview-name>.app.example.com per deploy.
Use a dedicated Preview hostname (previews.example.com) when
production already has subdomains, so the wildcard does not collide
with docs.example.com.
Preview, version, or stage?
| What you want | Use |
|---|---|
| Branch / PR with its own URL and isolated DOs | preview.of |
| Canary a percentage of live traffic | version.parent + version.traffic |
| Gradual rollout of this Worker | version.traffic |
| Inspect one upload without routing | version.traffic: 0 |
| Persistent env, or infra that must be fully isolated (new table, matching service bindings) | A separate Alchemy stage |
preview and version.parent cannot be set together.
Service bindings from a Preview currently resolve to the bound Worker's production deployment. Crons, queue consumers, and production routes stay on production. For an end-to-end multi-Worker PR, deploy a full stage instead.
Preview URLs are public. Protect them with
Cloudflare Access on the parent
Worker (access.previews stays on by default).