Previews give each branch an isolated, production-like environment under the same Worker. Each Preview is configured with its own variables, secrets, and bindings, served on its own URL, and has its own observability.
Worker Previews requires Wrangler 4.135.0 or later. Update the project dependency because project commands do not use a newer global installation.
Used Version URLs or Wrangler environments before? Refer to Compare workflows to understand how they differ from Previews and our recommended practices for branch testing.
Running npx wrangler preview creates or updates a Preview for your current branch under the same Worker. As you use npx wrangler deploy for production, use npx wrangler preview to test a branch before merging.
| Branch | Command | What happens |
|---|---|---|
main |
npx wrangler deploy |
Deploys to production with production settings. |
feature/login |
npx wrangler preview |
Creates or updates a Preview with its own settings. |
Each Preview gets two types of URLs. You can serve them on workers.dev, a custom domain, or both.
- Preview URL: always serves the latest deployment. Share this with your team so they always see the most up-to-date version of your branch.
- Deployment URL: points to one specific deploy and never changes. Use this to reference or compare exact versions, like linking a specific deploy in a PR review.
| Host type | Preview URL | Deployment URL |
|---|---|---|
workers.dev |
<preview-name>-<worker-name>.<subdomain>.workers.dev |
<deployment-id>-<worker-name>.<subdomain>.workers.dev |
| Custom domain | <preview-name>.app.example.com |
<deployment-id>-<preview-name>.app.example.com |
To prevent search engines from indexing your Preview, use its workers.dev URL, which includes an X-Robots-Tag: noindex response header. For custom domain Preview URLs, use Cloudflare Access.
Previews do not inherit production settings. Define them in the previews block of your Wrangler configuration file. When you run npx wrangler preview on a branch, Wrangler creates or updates its Preview using that branch's previews block. For more information, refer to Configuration.
Since secrets cannot be stored in the configuration file or version control, use commands to apply secrets to all new Previews or to an individual Preview.
Cloudflare automatically provisions a new Durable Object namespace and container instances for each Preview. KV, D1, R2, and other resources are isolated when you bind the Preview to a separate resource. For the full matrix, refer to Resources and isolation.
Workflow bindings use existing Workflows and do not create Preview-specific Workflows. Service bindings from a Preview call the bound Worker's production deployment. Routes and Cron Triggers target production. Queue consumers cannot target a Preview. For details, refer to Limitations.
Preview URLs are public by default. Use Cloudflare Access to require sign-in. You can protect all Previews on an account, one Worker's Previews, or specific hostnames. Details in Custom domains.
| Limit | Free plan | Paid plans |
|---|---|---|
| Previews per Worker | 100 | 500 |
| Deployments per Preview | 100 | 100 |
When a limit is reached, Cloudflare automatically deletes the oldest to make room:
- Preview limit: the Preview that was deployed to least recently is deleted.
- Deployment limit: the oldest deployment in that Preview is deleted.
You can also delete Previews yourself with npx wrangler preview delete --name <preview-name>. For a pull request cleanup example, refer to Delete closed pull request Previews.
- Get started - Set up your first Preview
- Configuration - Configure variables, secrets, bindings, and Base configuration
- Resources and isolation - Understand which resources are isolated or shared
- Limitations - Review current support gaps and workarounds