Adds docs for Worker Previews by korinne · Pull Request #28806 · cloudflare/cloudflare-docs

korinne · 2026-03-06T01:40:55Z

Summary

Draft documentation for Worker Previews

To dos

Needs actual API docs
Add Terraform resources
Audit / clean up old Preview URLs docs
Add details about wrangler secret put for previews
Add a nice diagram

… observability, and limits

…aults, endpoints, and walkthrough

…views section

…ews/ to /workers/previews/

…ons to Previews

…iew URLs section

…hroughout Previews docs

…m dashes, add doc links, use PackageManagers components

github-actions · 2026-03-06T01:41:18Z

This PR requires additional review attention because it affects the following areas:

Partials

This PR updates partial files, which are pieces of content used across multiple files in our Render component.

workers/custom_headers - view affected files

github-actions · 2026-03-06T01:42:03Z

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
`/public/__redirects`	`@cloudflare/content-engineering`, `@cloudflare/pcx-technical-writing`
`/src/content/changelog/`	`@cloudflare/pm-changelogs`, `@cloudflare/pcx-technical-writing`
`/src/content/docs/workers/ci-cd/`	`@irvinebroque`, `@aninibread`, `@GregBrimble`, `@cloudflare/pcx-technical-writing`, `@yomna-shousha`
`/src/content/docs/workers/`	`@cloudflare/workers-docs`, `@GregBrimble`, `@irvinebroque`, `@mikenomitch`, `@korinne`, `@WalshyDev`, `@cloudflare/deploy-config`, `@cloudflare/pcx-technical-writing`, `@cloudflare/wrangler`, `@mattietk`, `@cloudflare/dev-plat-leads`
`/src/content/docs/workers/static-assets`	`@irvinebroque`, `@GregBrimble`, `@WalshyDev`, `@cloudflare/deploy-config`, `@cloudflare/pcx-technical-writing`
`/src/content/docs/workers/wrangler/`	`@cloudflare/wrangler`, `@irvinebroque`, `@cloudflare/pcx-technical-writing`
`/src/content/partials/workers/`	`@cloudflare/workers-docs`, `@GregBrimble`, `@irvinebroque`, `@mikenomitch`, `@WalshyDev`, `@cloudflare/deploy-config`, `@cloudflare/pcx-technical-writing`, `@cloudflare/wrangler`, `@mattietk`

github-actions · 2026-03-06T01:55:59Z

Preview URL: https://e3ccd4f9.preview.developers.cloudflare.com
Preview Branch URL: https://korinne-worker-previews.preview.developers.cloudflare.com

Files with changes (up to 15)

github-actions · 2026-03-06T01:58:04Z

CI run failed: build logs

1000hz · 2026-03-13T15:12:55Z

- 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.
- You cannot currently configure Preview URLs to run on a subdomain other than [`workers.dev`](/workers/configuration/routing/workers-dev/).
- You cannot view logs for Preview URLs today, this includes Workers Logs, Wrangler tail and Logpush.
+This page has moved. For the latest documentation on Previews, refer to [Previews](/workers/previews/).


this page is no longer reachable because of the redirect, no? should we just delete this file?

1000hz · 2026-03-13T16:02:32Z

+
+### From the dashboard
+
+Go to your Worker > **Settings**, and you will see a banner for setting up your default Preview settings. This walks you through the bindings, environment variables, and [observability](#observability-and-logging) settings you want every Preview to start with. This is the fastest way to get your whole team set up — anyone who creates a Preview (manually or by pushing a branch) gets the same configuration without needing to specify it themselves.


This banner will only appear if the Worker already has production bindings (and will likely be removed or retooled before we launch). Brand new Workers won't require any unique setup flows for Previews; configuring a Worker with Previews settings is just like configuring a Worker with Production settings. In other words, we should just point users to configuring their Previews settings from the Settings and Bindings tabs.

1000hz · 2026-03-13T16:18:38Z

I'm pretty skeptical of the value of this page. The important reference information will already be captured by our actual API reference docs (and OpenAPI schema), and the high-level feature concept explanations don't belong in a page focused on interacting with the API. Topics like how settings provided at deployment time interact with Previews settings probably shouldn't be presented through the narrow lens of the API.

We don't document other APIs in this way. Why Previews? If it's to aid in agent discoverability, I think API reference docs (or just relying on wrangler commands instead of making API requests directly) will suffice.

1000hz · 2026-03-13T17:01:51Z

+	InlineBadge,
+} from "~/components";
+
+A **Preview** is an isolated copy of your Worker that runs on its own URL, so you can test changes before deploying to production. A Worker can have many Previews running at the same time, each isolated from each other. Each Preview runs with its own [bindings](/workers/runtime-apis/bindings/), [environment variables](/workers/configuration/environment-variables/), and [secrets](/workers/configuration/secrets/), so your preview traffic never touches your production data.


Suggested change

A **Preview** is an isolated copy of your Worker that runs on its own URL, so you can test changes before deploying to production. A Worker can have many Previews running at the same time, each isolated from each other. Each Preview runs with its own [bindings](/workers/runtime-apis/bindings/), [environment variables](/workers/configuration/environment-variables/), and [secrets](/workers/configuration/secrets/), so your preview traffic never touches your production data.

A **Preview** is a separate instance of your Worker that runs on its own URL, so you can test changes before deploying to production. Previews run with their own set of [bindings](/workers/runtime-apis/bindings/), [environment variables](/workers/configuration/environment-variables/), and [secrets](/workers/configuration/secrets/), so your preview traffic never touches your production data.

A Worker can have many Previews running at the same time, each isolated from each other

This is only true insofar as two Previews don't share the same binding configuration. This isn't a claim we can reliably make.

1000hz · 2026-03-13T17:17:47Z

+git checkout -b new-feature
+```
+
+3. Deploy a Preview:


We should probably include git push as an option here (assuming the user has connected this Worker to their git repo in the interim...)

I wonder if a "quick start" focused on Previews is actually valuable. Previews are a means to and end of supporting the overall SDLC of your Workers application, not the destination itself.

1000hz · 2026-03-13T19:00:58Z

+| Preview    | `my-feature.app.example.com`        |
+| Deployment | `f498jo-my-feature.app.example.com` |
+
+To enable Previews on a custom domain via the API, set `previews_enabled` to `true`:


Feels out-of-place to show how to do this via API.

1000hz · 2026-03-13T19:02:04Z

+
+## Secure access to Previews
+
+To restrict who can access your Preview URLs, you can enable [Cloudflare Access](/cloudflare-one/access-controls/policies/) with a single click in your Worker's settings. This protects both Preview URLs and Deployment URLs.


Suggested change

To restrict who can access your Preview URLs, you can enable [Cloudflare Access](/cloudflare-one/access-controls/policies/) with a single click in your Worker's settings. This protects both Preview URLs and Deployment URLs.

To restrict who can access your Previews, you can enable [Cloudflare Access](/cloudflare-one/access-controls/policies/) with a single click in your Worker's settings. This protects both Preview URLs and Deployment URLs.

1000hz · 2026-03-13T19:05:23Z

+To restrict who can access your Preview URLs, you can enable [Cloudflare Access](/cloudflare-one/access-controls/policies/) with a single click in your Worker's settings. This protects both Preview URLs and Deployment URLs.
+
+1. Go to **Workers & Pages** > your Worker > **Settings** > **Domains & Routes**.
+2. For Preview URLs, select **Enable Cloudflare Access**.


Suggested change

2. For Preview URLs, select **Enable Cloudflare Access**.

2. Select **Enable Cloudflare Access** within the actions menu of **Preview URLs**.

1000hz · 2026-03-13T19:05:53Z

+
+## Observability and logging
+
+Each Preview runs its own observability and logging settings, independent of your production Worker. This means you can:


Suggested change

Each Preview runs its own observability and logging settings, independent of your production Worker. This means you can:

Each Preview has its own observability and logging settings, independent of your production Worker. This means you can:

1000hz · 2026-03-13T19:10:32Z

+- Enable [Logpush](/workers/observability/logpush/) to send a Preview's logs to your own storage for debugging.
+- Attach [Tail Workers](/workers/observability/logs/tail-workers/) to a Preview to pipe its logs into a custom analysis pipeline.
+
+Configure these in the dashboard under **Workers & Pages** > your Worker > **Settings** > **Preview Defaults**, and Cloudflare applies them to every Preview created for that Worker. For details on how observability settings are structured, refer to the [Preview object](/workers/previews/api/#preview-object).


Suggested change

Configure these in the dashboard under **Workers & Pages** > your Worker > **Settings** > **Preview Defaults**, and Cloudflare applies them to every Preview created for that Worker. For details on how observability settings are structured, refer to the [Preview object](/workers/previews/api/#preview-object).

Configure observability settings for all Previews in the dashboard under **Workers & Pages** > your Worker > **Settings** > **Observability**. You can also configure these settings for an individual Preview under **Workers & Pages** > your Worker > **Previews** > your Preview > **Settings**.

1000hz · 2026-03-13T19:22:25Z

+Run `wrangler preview` from your project directory to build your code locally and deploy it as a Preview:
+
+<PackageManagers type="exec" pkg="wrangler" args="preview" />
+
+By default, Wrangler names the Preview after your current Git branch. You can also provide a name explicitly:
+
+<PackageManagers type="exec" pkg="wrangler" args="preview --name my-feature" />
+
+If a Preview with that name does not exist yet, Wrangler creates it. If it already exists, Wrangler creates a new deployment within it. Each time you run `wrangler preview`, Wrangler prints the Preview URL and Deployment URL to your terminal.
+
+Use this for ad-hoc testing, external CI/CD pipelines, or when you are not using a Git-based workflow.


Suggested change

Run `wrangler preview` from your project directory to build your code locally and deploy it as a Preview:

<PackageManagers type="exec" pkg="wrangler" args="preview" />

By default, Wrangler names the Preview after your current Git branch. You can also provide a name explicitly:

<PackageManagers type="exec" pkg="wrangler" args="preview --name my-feature" />

If a Preview with that name does not exist yet, Wrangler creates it. If it already exists, Wrangler creates a new deployment within it. Each time you run `wrangler preview`, Wrangler prints the Preview URL and Deployment URL to your terminal.

Use this for ad-hoc testing, external CI/CD pipelines, or when you are not using a Git-based workflow.

Run `wrangler preview` from your project directory to build your code locally and deploy it as a Preview. Use this for ad-hoc testing, external CI/CD pipelines, or when you are not using a Git-based workflow.

<PackageManagers type="exec" pkg="wrangler" args="preview" />

By default, Wrangler names the Preview after your current Git branch. You can also provide a name explicitly:

<PackageManagers type="exec" pkg="wrangler" args="preview --name my-feature" />

github-actions · 2026-03-28T03:52:55Z

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label is helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant).

korinne added 8 commits March 5, 2026 17:05

[Workers] Add Previews overview page with intro, setup, deploy, URLs,…

e60ca5e

… observability, and limits

[Workers] Add Previews API reference with core concepts, objects, def…

b34bdee

…aults, endpoints, and walkthrough

[Workers] Redirect old configuration/previews page to new workers/pre…

aed1c98

…views section

[Workers] Update all internal links from /workers/configuration/previ…

0972b8a

…ews/ to /workers/previews/

[Workers] Add enable/disable, custom domains, and secure access secti…

9ecfe93

…ons to Previews

[Workers] Fix broken anchor links to point to new enable/disable Prev…

27bdd78

…iew URLs section

[Workers] Bold first-use terms and add cross-reference anchor links t…

9bd5306

…hroughout Previews docs

[Workers] Polish Previews docs: remove Beta badges, replace -- with e…

e3ccd4f

…m dashes, add doc links, use PackageManagers components

github-actions bot added product:workers Related to Workers product product:changelog size/xl labels Mar 6, 2026

github-actions bot assigned aninibread, GregBrimble, irvinebroque and yomna-shousha Mar 6, 2026

github-actions bot assigned MattieTK, mikenomitch and WalshyDev Mar 6, 2026

1000hz reviewed Mar 13, 2026

View reviewed changes

1000hz mentioned this pull request Mar 20, 2026

feat(wrangler): Add a new wrangler preview command group for Worker Previews cloudflare/workers-sdk#12983

Merged

5 tasks

github-actions bot added the stale label Mar 28, 2026


		### From the dashboard

		Go to your Worker > Settings, and you will see a banner for setting up your default Preview settings. This walks you through the bindings, environment variables, and [observability](#observability-and-logging) settings you want every Preview to start with. This is the fastest way to get your whole team set up — anyone who creates a Preview (manually or by pushing a branch) gets the same configuration without needing to specify it themselves.


		## Secure access to Previews

		To restrict who can access your Preview URLs, you can enable [Cloudflare Access](/cloudflare-one/access-controls/policies/) with a single click in your Worker's settings. This protects both Preview URLs and Deployment URLs.

	To restrict who can access your Preview URLs, you can enable [Cloudflare Access](/cloudflare-one/access-controls/policies/) with a single click in your Worker's settings. This protects both Preview URLs and Deployment URLs.
	To restrict who can access your Previews, you can enable [Cloudflare Access](/cloudflare-one/access-controls/policies/) with a single click in your Worker's settings. This protects both Preview URLs and Deployment URLs.

	2. For Preview URLs, select Enable Cloudflare Access.
	2. Select Enable Cloudflare Access within the actions menu of Preview URLs.


		## Observability and logging

		Each Preview runs its own observability and logging settings, independent of your production Worker. This means you can:

	Each Preview runs its own observability and logging settings, independent of your production Worker. This means you can:
	Each Preview has its own observability and logging settings, independent of your production Worker. This means you can:

	Configure these in the dashboard under Workers & Pages > your Worker > Settings > Preview Defaults, and Cloudflare applies them to every Preview created for that Worker. For details on how observability settings are structured, refer to the [Preview object](/workers/previews/api/#preview-object).
	Configure observability settings for all Previews in the dashboard under Workers & Pages > your Worker > Settings > Observability. You can also configure these settings for an individual Preview under Workers & Pages > your Worker > Previews > your Preview > Settings.

Conversation

korinne commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

To dos

Uh oh!

github-actions bot commented Mar 6, 2026

Partials

Uh oh!

github-actions bot commented Mar 6, 2026

Uh oh!

github-actions bot commented Mar 6, 2026

Uh oh!

github-actions bot commented Mar 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

korinne commented Mar 6, 2026 •

edited

Loading