|
1 | 1 | --- |
2 | | -pcx_content_type: configuration |
| 2 | +pcx_content_type: navigation |
3 | 3 | title: Preview URLs |
4 | | -head: [] |
| 4 | +head: |
| 5 | + - tag: meta |
| 6 | + attrs: |
| 7 | + name: robots |
| 8 | + content: noindex |
5 | 9 | sidebar: |
6 | | - badge: |
7 | | - text: Beta |
| 10 | + hidden: true |
8 | 11 | description: Preview URLs allow you to preview new versions of your project without deploying it to production. |
9 | 12 | --- |
10 | 13 |
|
11 | | -import { Render, WranglerConfig, DashButton } from "~/components"; |
12 | | - |
13 | | -# Overview |
14 | | - |
15 | | -Preview URLs allow you to preview new versions of your Worker without deploying it to production. |
16 | | - |
17 | | -There are two types of preview URLs: |
18 | | - |
19 | | -- **Versioned Preview URLs**: A unique URL generated automatically for each new version of your Worker. |
20 | | -- **Aliased Preview URLs**: A static, human-readable alias that you can manually assign to a Worker version. |
21 | | - |
22 | | -Both preview URL types follow the format: `<VERSION_PREFIX OR ALIAS>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev`. |
23 | | - |
24 | | -Preview URLs can be: |
25 | | - |
26 | | -- Integrated into CI/CD pipelines, allowing automatic generation of preview environments for every pull request. |
27 | | -- Used for collaboration between teams to test code changes in a live environment and verify updates. |
28 | | -- Used to test new API endpoints, validate data formats, and ensure backward compatibility with existing services. |
29 | | - |
30 | | -When testing zone level performance or security features for a version, we recommend using [version overrides](/workers/configuration/versions-and-deployments/gradual-deployments/#version-overrides) so that your zone's performance and security settings apply. |
31 | | - |
32 | | -:::note |
33 | | -Preview URLs are only available for Worker versions uploaded after 2024-09-25. |
34 | | -::: |
35 | | - |
36 | | -## Types of Preview URLs |
37 | | - |
38 | | -### Versioned Preview URLs |
39 | | - |
40 | | -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`. |
41 | | - |
42 | | -New versions of a Worker are created when you run: |
43 | | - |
44 | | -- [`wrangler deploy`](/workers/wrangler/commands/#deploy) |
45 | | -- [`wrangler versions upload`](/workers/wrangler/commands/#versions-upload) |
46 | | -- Or when you make edits via the Cloudflare dashboard |
47 | | - |
48 | | -If Preview URLs have been enabled, they are public and available immediately after version creation. |
49 | | - |
50 | | -:::note |
51 | | -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/). |
52 | | -::: |
53 | | - |
54 | | -#### View versioned preview URLs using Wrangler |
55 | | - |
56 | | -The [`wrangler versions upload`](/workers/wrangler/commands/#versions-upload) command uploads a new [version](/workers/configuration/versions-and-deployments/#versions) of your Worker and returns a preview URL for each version uploaded. |
57 | | - |
58 | | -#### View versioned preview URLs on the Workers dashboard |
59 | | - |
60 | | -1. In the Cloudflare dashboard, go to the **Workers & Pages** page. |
61 | | - |
62 | | - <DashButton url="/?to=/:account/workers-and-pages" /> |
63 | | - |
64 | | -2. Select your Worker. |
65 | | -3. Go to the **Deployments** tab, and find the version you would like to view. |
66 | | - |
67 | | -### Aliased preview URLs |
68 | | - |
69 | | -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: |
70 | | -`<ALIAS>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev` |
71 | | - |
72 | | -:::note |
73 | | -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/). |
74 | | -::: |
75 | | - |
76 | | -#### Create an Alias |
77 | | - |
78 | | -Aliases may be created during `versions upload`, by providing the `--preview-alias` flag with a valid alias name: |
79 | | - |
80 | | -```bash |
81 | | -wrangler versions upload --preview-alias staging |
82 | | -``` |
83 | | - |
84 | | -The resulting alias would be associated with this version, and immediately available at: |
85 | | -`staging-<WORKER_NAME>.<SUBDOMAIN>.workers.dev` |
86 | | - |
87 | | -#### Rules and limitations |
88 | | - |
89 | | -- Aliases may only be created during version upload. |
90 | | -- Aliases must use only lowercase letters, numbers, and dashes. |
91 | | -- Aliases must begin with a lowercase letter. |
92 | | -- The alias and Worker name combined (with a dash) must not exceed 63 characters due to DNS label limits. |
93 | | -- 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. |
94 | | - |
95 | | -## Manage access to Preview URLs |
96 | | - |
97 | | -When enabled, all preview URLs are available publicly. You can use [Cloudflare Access](/cloudflare-one/access-controls/policies/) 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/access-controls/policies/). |
98 | | - |
99 | | -To limit your preview URLs to authorized emails only: |
100 | | - |
101 | | -1. In the Cloudflare dashboard, go to the **Workers & Pages** page. |
102 | | - |
103 | | - <DashButton url="/?to=/:account/workers-and-pages" /> |
104 | | - |
105 | | -2. In **Overview**, select your Worker. |
106 | | -3. Go to **Settings** > **Domains & Routes**. |
107 | | -4. For Preview URLs, click **Enable Cloudflare Access**. |
108 | | -5. Optionally, to configure the Access application, click **Manage Cloudflare Access**. There, you can change the email addresses you want to authorize. View [Access policies](/cloudflare-one/access-controls/policies/#selectors) to learn about configuring alternate rules. |
109 | | -6. [Validate the Access JWT](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/#cloudflare-workers-example) in your Worker script using the audience (`aud`) tag and JWKs URL provided. |
110 | | - |
111 | | -## Toggle Preview URLs (Enable or Disable) |
112 | | - |
113 | | -Note: |
114 | | - |
115 | | -- Preview URLs are enabled by default when `workers_dev` is enabled. |
116 | | -- Preview URLs are disabled by default when `workers_dev` is disabled. |
117 | | -- Disabling Preview URLs will disable routing to both versioned and aliased preview URLs. |
118 | | - |
119 | | -### From the Dashboard |
120 | | - |
121 | | -To toggle Preview URLs for a Worker: |
122 | | - |
123 | | -1. In the Cloudflare dashboard, go to the **Workers & Pages** page. |
124 | | - |
125 | | - <DashButton url="/?to=/:account/workers-and-pages" /> |
126 | | - |
127 | | -2. In **Overview**, select your Worker. |
128 | | -3. Go to **Settings** > **Domains & Routes**. |
129 | | -4. For Preview URLs, click **Enable** or **Disable**. |
130 | | -5. Confirm your action. |
131 | | - |
132 | | -### From the [Wrangler configuration file](/workers/wrangler/configuration/) |
133 | | - |
134 | | -:::note |
135 | | -Wrangler 3.91.0 or higher is required to use this feature. |
136 | | -::: |
137 | | - |
138 | | -:::note |
139 | | -Older Wrangler versions will default to Preview URLs being enabled. |
140 | | -::: |
141 | | - |
142 | | -To toggle Preview URLs for a Worker, include any of the following in your Worker's Wrangler file: |
143 | | - |
144 | | -<WranglerConfig> |
145 | | - |
146 | | -```jsonc |
147 | | -{ |
148 | | - "preview_urls": true |
149 | | -} |
150 | | -``` |
151 | | - |
152 | | -</WranglerConfig> |
153 | | - |
154 | | -<WranglerConfig> |
155 | | - |
156 | | -```jsonc |
157 | | -{ |
158 | | - "preview_urls": false |
159 | | -} |
160 | | -``` |
161 | | - |
162 | | -</WranglerConfig> |
163 | | - |
164 | | -If not given, `preview_urls = workers_dev` is the default. |
165 | | - |
166 | | -:::caution |
167 | | -If you enable or disable Preview URLs in the Cloudflare dashboard, but do not update your Worker's Wrangler file accordingly, the Preview URLs status will change the next time you deploy your Worker with Wrangler. |
168 | | -::: |
169 | | - |
170 | | -## Limitations |
171 | | - |
172 | | -- Preview URLs are not generated for Workers that implement a [Durable Object](/durable-objects/). |
173 | | -- Preview URLs are not currently generated for [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/) [user Workers](/cloudflare-for-platforms/workers-for-platforms/how-workers-for-platforms-works/#user-workers). This is a temporary limitation, we are working to remove it. |
174 | | -- You cannot currently configure Preview URLs to run on a subdomain other than [`workers.dev`](/workers/configuration/routing/workers-dev/). |
175 | | -- You cannot view logs for Preview URLs today, this includes Workers Logs, Wrangler tail and Logpush. |
| 14 | +This page has moved. For the latest documentation on Previews, refer to [Previews](/workers/previews/). |
0 commit comments