diff --git a/src/content/docs/workers/configuration/multipart-upload-metadata.mdx b/src/content/docs/workers/configuration/multipart-upload-metadata.mdx index ebc1828217ccf0e..03c8c7ebf513e5d 100644 --- a/src/content/docs/workers/configuration/multipart-upload-metadata.mdx +++ b/src/content/docs/workers/configuration/multipart-upload-metadata.mdx @@ -109,6 +109,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 diff --git a/src/content/docs/workers/configuration/previews.mdx b/src/content/docs/workers/configuration/previews.mdx index 645cbd74bab27ba..0df8f85ff32eb7e 100644 --- a/src/content/docs/workers/configuration/previews.mdx +++ b/src/content/docs/workers/configuration/previews.mdx @@ -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: `-..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: + +- **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: `-..workers.dev`. Preview URLs can be: @@ -24,22 +31,66 @@ 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 + +### Versioned 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 `-..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 versioned 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 versioned 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 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: +`-..workers.dev` + +:::note +Minimum required Wrangler version: `4.21.0`. Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/). +::: + +#### Create an Alias + +Aliases may be created during `versions upload`, by providing the `--preview-alias` flag with a valid alias name: + +```bash +wrangler versions upload --preview-alias staging +``` + +The resulting alias would be associated with this version, and immediately available at: +`staging-..workers.dev` + +#### Rules and limitations + +- 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 20 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: @@ -67,6 +118,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 versioned and aliased preview URLs. + ### Disabling Preview URLs in the dashboard To disable Preview URLs for a Worker: diff --git a/src/content/docs/workers/wrangler/commands.mdx b/src/content/docs/workers/wrangler/commands.mdx index db561283dc6200e..543cbd1cd8b3a61 100644 --- a/src/content/docs/workers/wrangler/commands.mdx +++ b/src/content/docs/workers/wrangler/commands.mdx @@ -1464,6 +1464,8 @@ wrangler versions upload [OPTIONS] - Add a version tag. Accepts empty string. - `--message` - Add a version message. Accepts empty string. +- `--preview-alias` + - Creates an alias to this version. - `--name` - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/). - `--env`