← Workers / workers / versions-and-deployments

Preview URLs

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

There are two types of preview URLs:

• Versioned Preview URLs: A unique URL generated automatically for each new version of your Worker.
• Aliased 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.

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

If Preview URLs have been enabled, they are public and available immediately after version creation.

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

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

   Go to Workers & Pages ↗

2. Select your Worker.

3. Go to the Deployments tab, and find the version you would like to view.

Aliased preview URLs let you assign a persistent, readable alias to a specific Worker version. These are useful for linking to stable previews across many versions (e.g. to share an upcoming but still actively being developed new feature). A common workflow would be to assign an alias for the branch that you're working on. These types of preview URLs follow the same pattern as other preview URLs: <ALIAS>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev

Aliases may be created during versions upload, by providing the --preview-alias flag with a valid alias name:

wrangler versions upload --preview-alias staging

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

• 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.

When enabled, Preview URLs are available publicly. To require visitors to sign in before they can access Preview URLs, use Cloudflare Access.

Access can protect previews for one Worker or every Worker in an account. You can also protect both production and preview deployments.

To use details about the signed-in user in your Worker, read the user's identity from the validated JWT or the /cdn-cgi/access/get-identity endpoint.

Note:

• Preview URLs are enabled by default when workers_dev is enabled.
• Preview URLs are disabled by default when workers_dev is disabled.
• Disabling Preview URLs will disable routing to both versioned and aliased preview URLs.

To toggle Preview URLs for a Worker:

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

   Go to Workers & Pages ↗

2. In Overview, select your Worker.

3. Go to Settings > Domains & Routes.

4. For Preview URLs, click Enable or Disable.

5. Confirm your action.

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

{
	"preview_urls": true
}

preview_urls = true

{
	"preview_urls": false
}

preview_urls = false

If not given, preview_urls = workers_dev is the default.

• Preview URLs are not generated for Workers that implement a Durable Object, including Containers and Sandbox Workers. For Containers testing options, refer to Deploy Containers.
• 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 view logs for Preview URLs today, this includes Workers Logs, Wrangler tail and Logpush.