Preview URLs

Overview

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

There are two types of preview URLs:

• Version-Prefixed Preview URLs: A unique URL generated automatically for each new version of your Worker.
• Alias Preview URLs: A static, human-readable alias that you can manually assign to a Worker version.

Both preview URL types follow the format: <VERSION_PREFIX OR ALIAS>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev.

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 features for a version, we recommend 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.

Types of Preview URLs

Version-Prefixed Preview URLs

Every time you create a new version of your Worker, a unique static version preview URL is generated automatically. These URLs use a version prefix and follow the format <VERSION_PREFIX>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev.

New versions of a Worker are created when you run:

• wrangler deploy
• wrangler versions upload
• Or when you make edits via the Cloudflare dashboard

These URLs are public by default and available immediately after version creation.

Note

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

View version-prefixed 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 version-prefixed preview URLs on the Workers dashboard

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

Aliased Preview URLs

Aliased preview URLs let you assign a persistent, readable alias to a specific Worker version. These are useful for linking to stable previews across environments. These types of preview URLs follow the same pattern as other preview URLs: <ALIAS>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev

Note

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

Creating an Alias

Aliases may be created by explicitly defining setting an alias during a versions upload:

wrangler versions upload --alias staging

The resulting alias would be associated with this version, and immediately available at: staging-<WORKER_NAME>.<SUBDOMAIN>.workers.dev

Rules & Limitations

• Aliases may only be created during version upload.
• Aliases must use only lowercase letters and numbers.
• The alias and Worker name combined (with a dash) must not exceed 63 characters due to DNS label limits.
• Only the 50 most recently used aliases are retained. When a new alias is created beyond this limit, the least recently used alias is deleted.

Manage access to Preview URLs

By default, all 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.

Disabling Preview URLs

Disabling Preview URLs will disable routing to both version-prefixed and aliased URLs.

Disabling Preview URLs in the dashboard

To disable Preview URLs for a Worker:

1. Log in to the Cloudflare dashboard ↗ and select your account.
2. Go to Workers & Pages and in Overview, select your Worker.
3. Go to Settings > Domains & Routes.
4. On "Preview URLs" click "Disable".
5. Confirm you want to disable.

Disabling Preview URLs in the Wrangler configuration file

Note

Wrangler 3.91.0 or higher is required to use this feature.

To disable Preview URLs for a Worker, include the following in your Worker's Wrangler file:

wrangler.jsonc

{
  "preview_urls": false
}

wrangler.toml

preview_urls = false

When you redeploy your Worker with this change, Preview URLs will be disabled.

Warning

If you disable Preview URLs in the Cloudflare dashboard but do not update your Worker's Wrangler file with preview_urls = false, then Preview URLs will be re-enabled the next time you deploy your Worker with Wrangler.

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.