Skip to content

Draft: Document Alias Preview URLs #22578

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: production
Choose a base branch
from
+59 −4
Draft

Draft: Document Alias Preview URLs #22578

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/content/docs/workers/configuration/multipart-upload-metadata.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ These attributes are **not available** for immediately deployed uploads.
- Annotations object specific to the Worker version.
- `workers/message` specifies a custom message for the version.
- `workers/tag` specifies a custom identifier for the version.
- `workers/alias` specifies a custom alias for this version.

## Bindings

Expand Down
60 changes: 56 additions & 4 deletions src/content/docs/workers/configuration/previews.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,16 @@ description: Preview URLs allow you to preview new versions of your project with

import { Render, WranglerConfig } from "~/components";

# Overview

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

Every time you create a new [version](/workers/configuration/versions-and-deployments/#versions) of your Worker a unique preview URL is generated. Preview URLs take the format: `<VERSION_PREFIX>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev`. New [versions](/workers/configuration/versions-and-deployments/#versions) of a Worker are created on [`wrangler deploy`](/workers/wrangler/commands/#deploy), [`wrangler versions upload`](/workers/wrangler/commands/#upload) or when you make edits on the Cloudflare dashboard. By default, preview URLs are enabled and available publicly.
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:

Expand All @@ -24,22 +31,65 @@ When testing zone level performance or security features for a version, we recom

:::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](/workers/configuration/versions-and-deployments/#versions) 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`](/workers/wrangler/commands/#deploy)
- [`wrangler versions upload`](/workers/wrangler/commands/#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](/workers/wrangler/install-and-update/).
:::

## View preview URLs using wrangler
#### View version-prefixed preview URLs using Wrangler

The [`wrangler versions upload`](/workers/wrangler/commands/#upload) command uploads a new [version](/workers/configuration/versions-and-deployments/#versions) of your Worker and returns a preview URL for each version uploaded.

## View preview URLs on the Workers dashboard
#### View version-prefixed preview URLs on the Workers dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers) 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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:
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. These types of preview URLs follow the same pattern as other preview URLs:

I'm vetoing the word "environment" 😅

`<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](/workers/wrangler/install-and-update/).
:::

#### Creating an Alias

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

```bash
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, preview URLs are enabled and available publicly. You can use [Cloudflare Access](/cloudflare-one/policies/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](/cloudflare-one/policies/access).
By default, all preview URLs are enabled and available publicly. You can use [Cloudflare Access](/cloudflare-one/policies/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](/cloudflare-one/policies/access).

To limit your preview URLs to authorized emails only:

Expand Down Expand Up @@ -67,6 +117,8 @@ You must press enter after you input your Application domain for it to save. You

## 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:
Expand Down
2 changes: 2 additions & 0 deletions src/content/docs/workers/wrangler/commands.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1462,6 +1462,8 @@ wrangler versions upload [OPTIONS]
- Add a version tag. Accepts empty string.
- `--message` <Type text="string" /> <MetaInfo text="optional" />
- Add a version message. Accepts empty string.
- `--alias` <Type text="string" /> <MetaInfo text="optional" />
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Possible conflict with --alias, the bundle flag for aliasing modules?

- Creates an alias to this version.
- `--name` <Type text="string" /> <MetaInfo text="optional" />
- Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).
- `--env` <Type text="string" /> <MetaInfo text="optional" />
Expand Down
Loading