Preview URLs

Preview URLs allow you to preview new versions of your Worker without deploying it to production.

Every time you create a new version of your Worker a unique preview URL is generated. Preview URLs take the format: <VERSION_PREFIX>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev. New versions of a Worker are created on wrangler deploy, wrangler versions upload or when you make edits on the Cloudflare dashboard. By default, preview URLs are enabled and available publicly.

Preview URLs can be:

• Integrated into CI/CD pipelines, allowing automatic generation of preview environments for every pull request.
• Used for collaboration between teams to test code changes in a live environment and verify updates.
• Used to test new API endpoints, validate data formats, and ensure backward compatibility with existing services.

When testing zone level performance or security featues for a version, we recommended using version overrides so that your zone’s performance and security settings apply.

Note

Preview URLs are only available for Worker versions uploaded after 2024-09-25.

Minimum required Wrangler version: 3.74.0. Check your version by running wrangler --version. To update Wrangler, refer to Install/Update Wrangler.

View preview URLs using wrangler

The wrangler versions upload command uploads a new version of your Worker and returns a preview URL for each version uploaded.

View preview URLs on the Workers dashboard

1. Log in to the Cloudflare dashboard ↗ and select your project.
2. Head to the “Deployments” tab find the version you would like to view.

Manage access to Preview URLs

By default, preview URLs are enabled and available publicly. You can use Cloudflare Access to require visitors to authenticate before accessing preview URLs. You can limit access to yourself, your teammates, your organization, or anyone else you specify in your access policy.

To limit your preview URLs to authorized emails only:

1. Log in to the Cloudflare Access dashboard ↗.
2. Select your account.
3. Add an application.
4. Select Self Hosted.
5. Name your application (for example, “my-worker”) and add your workers.dev subdomain as the Application domain.

For example, if you want to secure preview URLs for a Worker running on my-worker.my-subdomain.workers.dev.

• Subdomain: *-my-worker
• Domain: my-subdomain.workers.dev

Note

You must press enter after you input your Application domain for it to save. You will see a “Zone is not associated with the current account” warning that you may ignore.

6. Go to the next page.
7. Add a name for your access policy (for example, “Allow employees access to preview URLs for my-worker”).
8. In the Configure rules section create a new rule with the Emails selector, or any other attributes which you wish to gate access to previews with.
9. Enter the emails you want to authorize. View access policies to learn about configuring alternate rules.
10. Go to the next page.
11. Add application.

Making Preview URLs inaccessible

Preview URLs run on your workers.dev subdomain. You can disable preview URLs to make them inaccessible.

Disable on the Cloudflare dashboard

1. Log into the Cloudflare dashboard ↗ and select your account.
2. Go to Workers > your Worker.
3. Go to Settings.
4. In the “Domains & Routes” section click “Disable” on “Preview URLs”.
5. Confirm you want to disable.

Disable in Wrangler

::note

Wrangler vXX or higher is required to use this feature. ::

In your wrangler.toml you can add preview_urls = false to disable preview URLs from being accessible.

name = "my-worker"
compatibility_date = "2024-01-01"
preview_urls = false

This will be applied when doing wrangler deploy or wrangler triggers deploy if using Gradual Deployments.

Limitations

• Preview URLs are not generated for Workers that implement a Durable Object.
• Preview URLs are not currently generated for Workers for Platforms user Workers. This is a temporary limitation, we are working to remove it.
• You cannot currently configure Preview URLs to run on a subdomain other than workers.dev.
• You cannot use wrangler tail, Workers Logs or other similar tools to view logs for preview URLs.