Podonnell/preview onboarding by podonnell-dev · Pull Request #15598 · cloudflare/workers-sdk

podonnell-dev · 2026-09-10T20:49:27Z

Fixes #[insert GH or internal issue link(s)].

Describe your change...

Tests
- Tests included/updated
- Automated tests not possible - manual testing has been completed as follows:
- Additional testing not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because:

A picture of a cute animal (not mandatory, but encouraged)

changeset-bot · 2026-09-10T20:49:35Z

🦋 Changeset detected

Latest commit: 8347afb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
wrangler	Patch
@cloudflare/vite-plugin	Patch
@cloudflare/vitest-plugin	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

workers-devprod · 2026-09-10T20:50:01Z

Codeowners approval required for this PR:

@cloudflare/wrangler

Show detailed file reviewers

.changeset/preview-onboarding-deployment.md: [@cloudflare/wrangler]
packages/deploy-helpers/src/deploy/deploy.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/deploy/helpers/placement.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/deploy/versions-upload.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/preview/api.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/preview/preview.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/preview/shared.ts: [@cloudflare/wrangler]
packages/workers-utils/src/config/environment.ts: [@cloudflare/wrangler]
packages/workers-utils/src/config/patch-config.ts: [@cloudflare/wrangler]
packages/workers-utils/src/config/validation.ts: [@cloudflare/wrangler]
packages/workers-utils/tests/config/validation/normalize-and-validate-config.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/preview-config.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/preview.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/api/pages/create-worker-bundle-contents.ts: [@cloudflare/wrangler]
packages/wrangler/src/preview/ensure-config.ts: [@cloudflare/wrangler]
packages/wrangler/src/preview/preview-config.ts: [@cloudflare/wrangler]
packages/wrangler/src/preview/preview.ts: [@cloudflare/wrangler]

pkg-pr-new · 2026-09-10T20:55:51Z

@cloudflare/autoconfig

npm i https://pkg.pr.new/@cloudflare/autoconfig@15598

@cloudflare/build-output-utils

npm i https://pkg.pr.new/@cloudflare/build-output-utils@15598

@cloudflare/codemods

npm i https://pkg.pr.new/@cloudflare/codemods@15598

@cloudflare/config

npm i https://pkg.pr.new/@cloudflare/config@15598

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@15598

@cloudflare/deploy-helpers

npm i https://pkg.pr.new/@cloudflare/deploy-helpers@15598

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@15598

miniflare

npm i https://pkg.pr.new/miniflare@15598

@cloudflare/pages-functions

npm i https://pkg.pr.new/@cloudflare/pages-functions@15598

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@15598

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@15598

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@15598

@cloudflare/vitest-plugin

npm i https://pkg.pr.new/@cloudflare/vitest-plugin@15598

@cloudflare/workers-auth

npm i https://pkg.pr.new/@cloudflare/workers-auth@15598

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@15598

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@15598

wrangler

npm i https://pkg.pr.new/wrangler@15598

commit: 8347afb

devin-ai-integration

Devin Review found 4 potential issues.

2 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)

devin-ai-integration · 2026-09-10T20:57:26Z

extractConfigBindings

+	const baseConversion: ProposedPreviewsConfig = baseConfig
+		? convertPreviewBaseToPreviewsConfig(baseConfig)
+		: { config: {}, omittedBindings: [] };


🟡 Production bindings disappear during onboarding

When Preview Base contains any setting, baseConversion.config replaces every generated production-binding placeholder. A production binding absent from Preview Base is deployed missing after onboarding.

Learn more

Production conversion creates placeholder entries for supported production bindings so users must choose Preview-safe replacements. Preview Base conversion contains only remotely configured Preview defaults. Once Preview Base has any configured value, the current flow selects its conversion alone and never merges or checks the production proposal. The later deployment reads only the newly written previews block through extractConfigBindings, so omitted binding names are absent at runtime.

Example: Production defines KV binding SESSIONS, while Preview Base only enables observability. Onboarding writes previews.observability, deploys without SESSIONS, and the Worker fails when it accesses env.SESSIONS. Wrangler must instead require a Preview-safe KV ID.

Recommended fix: Compare production binding names against both converted and omitted Preview Base bindings. Merge non-conflicting production placeholders into the proposed config, or stop with a complete snippet that includes every production binding absent from Preview Base.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-09-10T20:57:27Z

+	const manualBindings = productionConversion.omittedBindings.filter(
+		(productionBinding) =>
+			!baseConversion.omittedBindings.some(
+				(baseBinding) =>
+					baseBinding.name === productionBinding.name &&
+					baseBinding.type === productionBinding.type
+			)
+	);


🟡 Safe Preview Base replacements are rejected

When Preview Base replaces an unsupported production binding, manualBindings still marks it unresolved. Matching only omitted base bindings makes onboarding abort despite a deployable replacement.

Learn more

productionConversion.omittedBindings lists production bindings that cannot safely become placeholder configuration. A binding with the same name in baseConversion.config is already a Preview-safe replacement, but converted base bindings are not retained as references. The filter removes an item only when Preview Base also omitted the same name and type, which is the opposite case from a converted replacement.

Example: Production has a secret_text binding named TOKEN, and Preview Base has a plain_text binding named TOKEN. Preview Base converts TOKEN into previews.vars, but manualBindings retains the production secret and aborts onboarding. The Preview Base value could have been deployed safely.

Recommended fix: Have conversion return references for successfully converted bindings as well as omitted bindings. Treat a production omission as resolved when Preview Base supplies any compatible converted binding with that name, while preserving the existing behavior for remote-only omitted base bindings.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-09-10T20:57:28Z

+		case "ai":
+			if (binding.staging !== undefined) {
+				return null;


🟡 Disabled AI staging blocks onboarding

With staging: false, convertBinding treats the AI binding as unsupported because the property is defined. Preview onboarding then aborts and requests manual configuration for a normal AI binding.

Suggested change

case "ai":

if (binding.staging !== undefined) {

return null;

case "ai":

if (binding.staging === true) {

return null;

}

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-09-10T20:57:29Z

experimental_patchConfig

+	const format = configFormat(config.userConfigPath);
+	const canWriteConfig =
+		config.userConfigPath !== undefined &&
+		config.userConfigPath === config.configPath &&
+		(format === "toml" || JSON_CONFIG_FORMATS.includes(format));


🟡 Commented TOML onboarding crashes

For a commented TOML file, canWriteConfig allows automatic onboarding even though the patcher rejects comments. Accepting the prompt throws PatchConfigError instead of adding or presenting the configuration.

Learn more

Automatic onboarding calls experimental_patchConfig after the user accepts. That patcher refuses any TOML source containing # because TOML round-tripping loses comments. The writability gate checks only the file format, so a common commented wrangler.toml reaches this known failure after prompting.

Example: A project has wrangler.toml containing # Worker settings and no previews table. Preview Base has one variable. Wrangler prompts to add it, the user accepts, and the command fails without deploying or showing the copyable fallback snippet.

Recommended fix: Detect commented TOML before offering automatic writeback and use the existing manual-snippet error path. Alternatively, catch PatchConfigError around writePreviewsConfig and return a UserError containing the generated snippet.

Was this helpful? React with 👍 or 👎 to provide feedback.

podonnell-dev added 2 commits September 10, 2026 15:51

temp

f442c7c

temp

696f36b

podonnell-dev requested a review from workers-devprod as a code owner September 10, 2026 20:49

workers-devprod added this to workers-sdk Sep 10, 2026

github-project-automation Bot moved this to Untriaged in workers-sdk Sep 10, 2026

workers-devprod requested review from a team and NuroDev and removed request for a team September 10, 2026 20:49

add changeset

8347afb

podonnell-dev marked this pull request as draft September 10, 2026 20:53

devin-ai-integration Bot reviewed Sep 10, 2026

View reviewed changes

Navigation Menu

Uh oh!

Podonnell/preview onboarding - #15598

Podonnell/preview onboarding#15598
podonnell-dev wants to merge 3 commits into
cloudflare:mainfrom
podonnell-dev:podonnell/preview-onboarding

podonnell-dev commented Sep 10, 2026 •

edited by devin-ai-integration Bot

Loading

Uh oh!

changeset-bot Bot commented Sep 10, 2026 •

edited

Loading

Uh oh!

workers-devprod commented Sep 10, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Sep 10, 2026

Uh oh!

devin-ai-integration Bot left a comment

Uh oh!

devin-ai-integration Bot Sep 10, 2026

Uh oh!

devin-ai-integration Bot Sep 10, 2026

Uh oh!

devin-ai-integration Bot Sep 10, 2026

Uh oh!

devin-ai-integration Bot Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

podonnell-dev commented Sep 10, 2026 • edited by devin-ai-integration Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

workers-devprod commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Sep 10, 2026

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

podonnell-dev commented Sep 10, 2026 •

edited by devin-ai-integration Bot

Loading

changeset-bot Bot commented Sep 10, 2026 •

edited

Loading

workers-devprod commented Sep 10, 2026 •

edited

Loading