Version URLs

Version URLs, previously called preview URLs, let you access an uploaded version of your Worker before deploying it to production. A Version URL uses that Worker version's existing configuration and resources instead of creating a separate environment.

This is useful for testing a specific version directly. To test the version with your zone's performance or security settings, use version overrides.

For isolated branch or pull request testing, use Previews. To compare Previews, Version URLs, and Wrangler environments, refer to Compare workflows.

Version URLs use this format:

<version-prefix>-<worker-name>.<subdomain>.workers.dev

Aliased Version URLs use this format:

<alias>-<worker-name>.<subdomain>.workers.dev

Every time you create a new version of your Worker, Cloudflare can generate a unique Version URL for that version.

New versions are created when you run:

• wrangler deploy
• wrangler versions upload
• Dashboard code edits that save a new version

If Version URLs are enabled, the URL is public and available after version creation.

The wrangler versions upload command uploads a new version of your Worker and returns a Version URL for that version.

npx wrangler versions upload

1. In the Cloudflare dashboard, go to Workers & Pages.

   Go to Workers & Pages ↗

2. Select your Worker.

3. Go to Deployments.

4. Find the version you want to test.

Aliased Version URLs let you assign a readable alias to a specific Worker version. This can be useful when you want a stable URL for a manually uploaded version.

Create an alias during version upload with --preview-alias:

npx wrangler versions upload --preview-alias staging

The alias points at the version uploaded by that command:

staging-<worker-name>.<subdomain>.workers.dev

Aliases may only be created during version upload.

When enabled, Version URLs are publicly available. To require visitors to sign in, use Cloudflare Access.

Access can protect Version URLs for one Worker or every Worker in an account. You can also protect both production and version deployments.

To use details about the signed-in user in your Worker, read the user identity from the validated JSON Web Token (JWT) or the /cdn-cgi/access/get-identity endpoint.

When no Version URL setting exists, Version URLs follow the same default as your workers.dev route:

• If workers_dev is enabled, Version URLs are enabled by default.
• If workers_dev is disabled, Version URLs are disabled by default.
• Disabling Version URLs disables routing to Version URLs and aliased Version URLs.

1. In the Cloudflare dashboard, go to Workers & Pages.
2. Select your Worker.
3. Go to Settings > Domains & Routes.
4. Find Version URLs.
5. Select Enable or Disable.

To enable Version URLs, add preview_urls to your Wrangler config:

{
  "preview_urls": true
}

preview_urls = true

To disable Version URLs:

{
  "preview_urls": false
}

preview_urls = false

If preview_urls is omitted, Wrangler does not change an existing Version URL setting. Set preview_urls explicitly to change it.

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

• Version URLs are not generated for Workers that implement a Durable Object, including Containers and Sandbox Workers. For Containers testing options, refer to Deploy Containers.
• Version URLs are not generated for Workers for Platforms user Workers.
• You cannot configure Version URLs to run on a subdomain other than workers.dev.
• You cannot view logs for Version URLs with Workers Logs, Wrangler tail, or Logpush.