[Workers] preview-urls (#17113)

* preview-urls

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: Greg Brimble <[email protected]>

* feedback

* edits

---------

Co-authored-by: Greg Brimble <[email protected]>

Author: tanushree-sharma

src/content/docs/pages/configuration/preview-deployments.mdx

@@ -1,7 +1,6 @@
 ---
 pcx_content_type: concept
 title: Preview deployments
-
 ---
 
 Preview deployments allow you to preview new versions of your project without deploying it to production. To view preview deployments:
@@ -47,10 +46,8 @@ Note that this will only protect your preview deployments (for example, `373f31e
 
 :::note
 
-
 If you want to enable Access for your `*.pages.dev` domain and your custom domain along with your preview deployments, review [Known issues](/pages/platform/known-issues/#enable-access-on-your-pagesdev-domain) for instructions.
 
-
 :::
 
 ## Preview aliases

src/content/docs/workers/configuration/previews.mdx

@@ -0,0 +1,46 @@
+---
+pcx_content_type: configuration
+title: Preview URLs
+head: []
+sidebar:
+  badge:
+    text: Beta
+description: Preview URLs allow you to preview new versions of your project without deploying it to production.
+---
+
+import { Render } from "~/components";
+
+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. 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.
+
+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 featues for a version, we recommended using [version overrides](/workers/configuration/versions-and-deployments/gradual-deployments/#version-overrides) so that your zone's performance and security settings apply.
+
+:::note
+Preview URLs are only available for Worker versions uploaded after 2024-09-25.
+:::
+
+## View 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
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers) and select your project.
+2. Head to the "Deployments" tab find the version you would like to view.
+
+## Making Preview URLs inaccessible
+
+Preview URLs run on your [`workers.dev` subdomain](/workers/configuration/routing/workers-dev/). To make preview URLs inaccessible, you must disable your Workers `workers.dev` subdomain. Learn how to [disable your Workers `workers.dev` subdomain](/workers/configuration/routing/workers-dev/#disabling-workersdev).
+
+## Limitations
+
+- Preview URLs are not generated for Workers that implement a [Durable Object](/durable-objects/).
+- Preview URLs are not currently generated for [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/) [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers). This is a temporary limitation, we are working to remove it.
+- You cannot currently secure `workers.dev` URLs behind [Cloudflare Access](/cloudflare-one/policies/access/). This is a temporary limitation, we are working to remove it.

src/content/docs/workers/configuration/routing/index.mdx

@@ -5,21 +5,22 @@ head: []
 description: Connect your Worker to an external endpoint (via Routes, Custom
   Domains or a `workers.dev` subdomain) such that it can be accessed by the
   Internet.
-
 ---
 
 To allow a Worker to receive inbound HTTP requests, you must connect it to an external endpoint such that it can be accessed by the Internet.
 
 There are three types of routes:
 
-* [Custom Domains](/workers/configuration/routing/custom-domains): Routes to a domain or subdomain (such as `example.com` or `shop.example.com`) within a Cloudflare zone where the Worker is the origin.
+- [Custom Domains](/workers/configuration/routing/custom-domains): Routes to a domain or subdomain (such as `example.com` or `shop.example.com`) within a Cloudflare zone where the Worker is the origin.
 
-* [Routes](/workers/configuration/routing/routes/): Routes that are set within a Cloudflare zone where your origin server, if you have one, is behind a Worker that the Worker can communicate with.
+- [Routes](/workers/configuration/routing/routes/): Routes that are set within a Cloudflare zone where your origin server, if you have one, is behind a Worker that the Worker can communicate with.
 
-* [`workers.dev`](/workers/configuration/routing/workers-dev/): The `workers.dev` subdomain route automatically created for your Worker that you can disable.
+- [`workers.dev`](/workers/configuration/routing/workers-dev/): A `workers.dev` subdomain route is automatically created for each Worker to help you getting started quickly. You may chose to [disable](/workers/configuration/routing/workers-dev/) your `workers.dev` subdomain.
 
 ## What is best for me?
 
+It's recommended to run production Workers on a [Workers route or custom domain](/workers/configuration/routing/), rather than on your `workers.dev` subdomain. Your `workers.dev` subdomain is treated as a [Free website](https://www.cloudflare.com/plans/) and is intended for personal or hobby projects that aren't business-critical.
+
 Custom Domains are recommended for use cases where your Worker is your application's origin server. Custom Domains can also be invoked within the same zone via `fetch()`, unlike Routes.
 
 Routes are recommended for use cases where your application's origin server is external to Cloudflare. Note that Routes cannot be the target of a same-zone `fetch()` call.

src/content/docs/workers/configuration/routing/routes.mdx

@@ -1,7 +1,6 @@
 ---
 pcx_content_type: concept
 title: Routes
-
 ---
 
 ## Background
@@ -10,11 +9,11 @@ Routes allow users to map a URL pattern to a Worker. When a request comes in to
 
 Routes are a set of rules that evaluate against a request's URL. Routes are recommended for you if you have a designated application server you always need to communicate with. Calling `fetch()` on the incoming `Request` object will trigger a subrequest to your application server, as defined in the **DNS** settings of your Cloudflare zone.
 
-Routes add Workers functionality to your existing proxied hostnames, in front of your application server. These allow your  Workers to act as a proxy and perform any necessary work before reaching out to an application server behind Cloudflare.
+Routes add Workers functionality to your existing proxied hostnames, in front of your application server. These allow your Workers to act as a proxy and perform any necessary work before reaching out to an application server behind Cloudflare.
 
 ![Routes work with your applications defined in Cloudflare DNS](~/assets/images/workers/learning/routes-diagram.png)
 
-Routes can `fetch()` Custom Domains and take precedence if configured on the same hostname. If you would like to run a logging Worker in front of your application, for example, you can create a Custom Domain on your application Worker for `app.example.com`, and create a Route for your logging Worker at `app.example.com/*`.  Calling `fetch()` will invoke the application Worker on your Custom Domain. Note that Routes cannot be the target of a same-zone `fetch()` call.
+Routes can `fetch()` Custom Domains and take precedence if configured on the same hostname. If you would like to run a logging Worker in front of your application, for example, you can create a Custom Domain on your application Worker for `app.example.com`, and create a Route for your logging Worker at `app.example.com/*`. Calling `fetch()` will invoke the application Worker on your Custom Domain. Note that Routes cannot be the target of a same-zone `fetch()` call.
 
 ## Set up a route
 
@@ -26,14 +25,14 @@ To add a route, you must have:
 
 :::caution
 
-Route setup will differ depending on if your application's origin is a Worker or not. If your Worker is your application's origin, use [Custom Domains](/workers/configuration/routing/custom-domains/). 
+Route setup will differ depending on if your application's origin is a Worker or not. If your Worker is your application's origin, use [Custom Domains](/workers/configuration/routing/custom-domains/).
 :::
 
 If your Worker is not your application's origin, follow the instructions below to set up a route.
 
 :::note
 
-Routes can also be created via the API. Refer to the [Workers Routes API documentation](/api/operations/worker-routes-list-routes) for more information. 
+Routes can also be created via the API. Refer to the [Workers Routes API documentation](/api/operations/worker-routes-create-route) for more information.
 :::
 
 ### Set up a route in the dashboard
@@ -75,26 +74,7 @@ routes = [
 
 :::note
 
-The `zone_id` and `zone_name` options are interchangeable. However, if using Cloudflare for SaaS with a `*/*` pattern, use the `zone_name` option to avoid errors. Currently, [publishing `*/*` routes with a `zone_id` option fails with an `Invalid URL` error](https://github.com/cloudflare/workers-sdk/issues/2953). 
-:::
-
-## Routes with `workers.dev`
-
-When you create your Worker, a [`workers.dev`](/workers/configuration/routing/workers-dev/) route is automatically set up. Review your `workers.dev` route in your Worker > **Triggers** > **Routes**.
-
-To disable the `workers.dev` route, include the following in your Worker's `wrangler.toml` file:
-
-```toml
-workers_dev = false
-```
-
-When you redeploy your Worker with this change, the `workers.dev` route will be disabled.
-
-If you do not specify `workers_dev = false` but add a [`routes` component](/workers/wrangler/configuration/#routes) to your `wrangler.toml`, the value of `workers_dev` will be inferred as `false` on the next deploy.
-
-:::caution
-
-If you disable your `workers.dev` route in the Cloudflare dashboard but do not update your Worker's `wrangler.toml` file with `workers_dev = false`, the `workers.dev` route will re-enable the next time you publish your Worker. 
+The `zone_id` and `zone_name` options are interchangeable. However, if using Cloudflare for SaaS with a `*/*` pattern, use the `zone_name` option to avoid errors. Currently, [publishing `*/*` routes with a `zone_id` option fails with an `Invalid URL` error](https://github.com/cloudflare/workers-sdk/issues/2953).
 :::
 
 ## Matching behavior
@@ -116,19 +96,19 @@ A pattern to match all requests looks like this:
 
 While they look similar to a [regex](https://en.wikipedia.org/wiki/Regular_expression) pattern, route patterns follow specific rules:
 
-* The only supported operator is the wildcard (`*`), which matches zero or more of any character.
+- The only supported operator is the wildcard (`*`), which matches zero or more of any character.
 
-* Route patterns may not contain infix wildcards or query parameters. For example, neither `example.com/*.jpg` nor `example.com/?foo=*` are valid route patterns.
+- Route patterns may not contain infix wildcards or query parameters. For example, neither `example.com/*.jpg` nor `example.com/?foo=*` are valid route patterns.
 
-* When more than one route pattern could match a request URL, the most specific route pattern wins. For example, the pattern `www.example.com/*` would take precedence over `*.example.com/*` when matching a request for `https://www.example.com/`. The pattern `example.com/hello/*` would take precedence over `example.com/*` when matching a request for `example.com/hello/world`.
+- When more than one route pattern could match a request URL, the most specific route pattern wins. For example, the pattern `www.example.com/*` would take precedence over `*.example.com/*` when matching a request for `https://www.example.com/`. The pattern `example.com/hello/*` would take precedence over `example.com/*` when matching a request for `example.com/hello/world`.
 
-* Route pattern matching considers the entire request URL, including the query parameter string. Since route patterns may not contain query parameters, the only way to have a route pattern match URLs with query parameters is to terminate it with a wildcard, `*`.
+- Route pattern matching considers the entire request URL, including the query parameter string. Since route patterns may not contain query parameters, the only way to have a route pattern match URLs with query parameters is to terminate it with a wildcard, `*`.
 
-* The path component of route patterns is case sensitive, for example, `example.com/Images/*` and `example.com/images/*` are two distinct routes.
+- The path component of route patterns is case sensitive, for example, `example.com/Images/*` and `example.com/images/*` are two distinct routes.
 
-* For routes created before October 15th, 2023, the host component of route patterns is case sensitive, for example, `example.com/*` and `Example.com/*` are two distinct routes.
+- For routes created before October 15th, 2023, the host component of route patterns is case sensitive, for example, `example.com/*` and `Example.com/*` are two distinct routes.
 
-* For routes created on or after October 15th, 2023, the host component of route patterns is not case sensitive, for example, `example.com/*` and `Example.com/*` are equivalent routes.
+- For routes created on or after October 15th, 2023, the host component of route patterns is not case sensitive, for example, `example.com/*` and `Example.com/*` are equivalent routes.
 
 A route can be specified without being associated with a Worker. This will act to negate any less specific patterns. For example, consider this pair of route patterns, one with a Workers script and one without:
 
@@ -137,7 +117,7 @@ A route can be specified without being associated with a Worker. This will act t
 *example.com/images/*       -> worker-script
 ```
 
-In this example, all requests destined for example.com and whose paths are prefixed by `/images/` would be routed to `worker-script`, *except* for `/images/cat.png`, which would bypass Workers completely. Requests with a path of `/images/cat.png?foo=bar` would be routed to `worker-script`, due to the presence of the query string.
+In this example, all requests destined for example.com and whose paths are prefixed by `/images/` would be routed to `worker-script`, _except_ for `/images/cat.png`, which would bypass Workers completely. Requests with a path of `/images/cat.png?foo=bar` would be routed to `worker-script`, due to the presence of the query string.
 
 ## Validity
 
@@ -155,30 +135,28 @@ For example, `https://example.com/?anything` is not a valid route pattern.
 
 If you omit a scheme in your route pattern, it will match both `http://` and `https://` URLs. If you include `http://` or `https://`, it will only match HTTP or HTTPS requests, respectively.
 
-* `https://*.example.com/` matches `https://www.example.com/` but not `http://www.example.com/`.
+- `https://*.example.com/` matches `https://www.example.com/` but not `http://www.example.com/`.
 
-* `*.example.com/` matches both `https://www.example.com/` and `http://www.example.com/`.
+- `*.example.com/` matches both `https://www.example.com/` and `http://www.example.com/`.
 
 #### Hostnames may optionally begin with `*`
 
 If a route pattern hostname begins with `*`, then it matches the host and all subhosts. If a route pattern hostname begins with `*.`, then it only matches all subhosts.
 
-* `*example.com/` matches `https://example.com/` and `https://www.example.com/`.
+- `*example.com/` matches `https://example.com/` and `https://www.example.com/`.
 
-* `*.example.com/` matches `https://www.example.com/` but not `https://example.com/`.
+- `*.example.com/` matches `https://www.example.com/` but not `https://example.com/`.
 
 #### Paths may optionally end with `*`
 
 If a route pattern path ends with `*`, then it matches all suffixes of that path.
 
-* `https://example.com/path*` matches `https://example.com/path` and `https://example.com/path2` and `https://example.com/path/readme.txt`
+- `https://example.com/path*` matches `https://example.com/path` and `https://example.com/path2` and `https://example.com/path/readme.txt`
 
 :::caution
 
-
 There is a well-known bug associated with path matching concerning wildcards (`*`) and forward slashes (`/`) that is documented in [Known issues](/workers/platform/known-issues/).
 
-
 :::
 
 #### Domains and subdomains must have a DNS Record
@@ -187,8 +165,6 @@ All domains and subdomains must have a [DNS record](/dns/manage-dns-records/how-
 
 :::caution
 
-
 If you have previously used the Cloudflare dashboard to add an `AAAA` record for `myname` to `example.com`, pointing to `100::` (the [reserved IPv6 discard prefix](https://tools.ietf.org/html/rfc6666)), Cloudflare recommends creating a [Custom Domain](/workers/configuration/routing/custom-domains/) pointing to your Worker instead.
 
-
 :::