Guide setup of previews block by GregBrimble · Pull Request #15478 · cloudflare/workers-sdk

GregBrimble · 2026-09-02T21:55:45Z

Fixes WC-5927 and WC-5834.

Primarily improves the onboarding experience for wrangler preview: guides users along setting up their previews block of config.

Additionally fixes two bug-ish-things: D1's database_id vs. id field, and adds support for placement in the previews block of config (already supported by the API). Best reviewed by commit.

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: private beta

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

changeset-bot · 2026-09-02T21:55:51Z

🦋 Changeset detected

Latest commit: 5057179

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

This PR includes changesets to release 3 packages

Name	Type
wrangler	Minor
@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-02T21:56:15Z

Codeowners approval required for this PR:

@cloudflare/wrangler

Show detailed file reviewers

.changeset/dry-camels-buy.md: [@cloudflare/wrangler]
.changeset/gold-spoons-sin.md: [@cloudflare/wrangler]
.changeset/polite-rings-make.md: [@cloudflare/wrangler]
packages/deploy-helpers/src/deploy/deploy.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/deploy/helpers/create-worker-upload-form.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/deploy/helpers/placement.ts: [@cloudflare/wrangler]
packages/deploy-helpers/src/deploy/helpers/provision-bindings.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/settings.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/src/map-worker-metadata-bindings.ts: [@cloudflare/wrangler]
packages/workers-utils/src/types.ts: [@cloudflare/wrangler]
packages/workers-utils/tests/config/patch-config.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/api/startDevWorker/utils.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/init.test.ts: [@cloudflare/wrangler]
packages/wrangler/src/tests/preview.settings.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/api/startDevWorker/utils.ts: [@cloudflare/wrangler]
packages/wrangler/src/preview/base-config/secrets/list.ts: [@cloudflare/wrangler]
packages/wrangler/src/preview/preview.ts: [@cloudflare/wrangler]

devin-ai-integration

Note

This report is out of date. Scroll down for Devin Review's latest report on this PR.

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-02T22:00:53Z

 	},
 	handler: async function previewHandler(args, { config }) {
 		const accountId = await requireAuth(config);
+		const previewConfig = await ensurePreviewsConfig(accountId, args, config);


🟡 Ignore flag imports remote settings

With --ignore-base-config and no local previews block, ensurePreviewsConfig still requires remote settings. The command aborts or copies settings excluded by the flag.

Prompt for agents

Update packages/wrangler/src/preview/preview.ts so ensurePreviewsConfig knows whether --ignore-base-config was supplied. When the flag is true, do not fetch, copy, or require the remote Preview Base configuration. Preserve any intended guidance for locally configured production bindings without contradicting the flag's local-only behavior. Add coverage for a missing local previews block with a non-empty remote base config and --ignore-base-config.

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

devin-ai-integration · 2026-09-02T22:00:55Z

 				"logpush",
 				"observability",
 				"limits",
+				"placement",


🟡 Preview placement bypasses validation

A malformed previews.placement passes validatePreviewsConfig because it is only allowlisted. Preview commands can then crash or send invalid placement.

Prompt for agents

Validate previews.placement in validatePreviewsConfig using the same placement shape and constraints as top-level placement, while reporting the nested previews.placement field path correctly. Add validation tests for non-object values, invalid modes, mutually exclusive targeted fields, and valid smart and targeted configurations.

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

devin-ai-integration · 2026-09-02T22:00:56Z

+	...baseConfig
+}: PreviewBaseConfig): PreviewsConfig {
+	const bindings = mapWorkerMetadataBindings(
+		Object.entries(env ?? {}).map(([name, binding]) => ({
+			name,


🟡 Imported bindings lose behavior options

When remote AI or service bindings include staging or cross_account_grant, mapWorkerMetadataBindings drops them. Confirming setup silently changes subsequent preview bindings.

Prompt for agents

Make the Preview Base env-to-config conversion in packages/wrangler/src/preview/preview.ts lossless for all binding properties supported by PreviewsConfig and extractConfigBindings. In particular, preserve AI staging and service cross_account_grant. Either extend mapWorkerMetadataBindings in workers-utils without changing unrelated callers or introduce a preview-specific conversion. Add round-trip tests for these options.

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

devin-ai-integration · 2026-09-02T22:00:57Z

+		);
+	}
+	if (key === "binding" || key === "name" || key === "type") {
+		return value;


🟡 Generated binding template is invalid

Typed options such as AI staging, queue delays, or rate-limit numbers become strings in replaceProductionConfigValues. The suggested block fails configuration validation.

Prompt for agents

Replace production resource identifiers and user values selectively rather than recursively replacing every primitive. Preserve typed behavioral fields such as booleans and numbers, and preserve non-resource configuration that is safe to reuse. Ensure every generated previews snippet passes normal config validation once required resource placeholders are replaced. Add tests for AI staging, queue options, and rate-limit simple values.

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

pkg-pr-new · 2026-09-02T22:04:31Z

@cloudflare/autoconfig

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

@cloudflare/build-output-utils

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

@cloudflare/codemods

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

@cloudflare/config

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

create-cloudflare

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

@cloudflare/deploy-helpers

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-functions

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-plugin

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

@cloudflare/workers-auth

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

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

wrangler

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

commit: 5057179

devin-ai-integration

Note

This report is out of date. Scroll down for Devin Review's latest report on this PR.

Devin Review found 3 new potential issues.

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

devin-ai-integration · 2026-09-04T15:16:56Z

+	const placement = previews?.placement ?? config.placement;
+	if (placement) {
+		previewDefaults.placement = parseConfigPlacement(placement);


🟡 Preview placement cannot be disabled

With previews.placement.mode set to off, assemblePreviewDefaults omits placement while merging remote settings. Existing placement remains active despite the override.

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

…wrangler preview`

GregBrimble requested a review from workers-devprod as a code owner September 2, 2026 21:55

workers-devprod requested review from a team and NuroDev and removed request for a team September 2, 2026 21:56

GregBrimble force-pushed the guide-setup-of-previews-block branch from 816057a to c4cc25c Compare September 2, 2026 22:00

devin-ai-integration Bot reviewed Sep 2, 2026

View reviewed changes

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

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

This comment was marked as resolved.

Sign in to view

GregBrimble force-pushed the guide-setup-of-previews-block branch from c4cc25c to 721676c Compare September 3, 2026 13:52

This comment was marked as resolved.

Sign in to view

GregBrimble force-pushed the guide-setup-of-previews-block branch 2 times, most recently from 1ba678a to f7f4716 Compare September 4, 2026 15:13

devin-ai-integration Bot reviewed Sep 4, 2026

View reviewed changes

GregBrimble added 2 commits September 4, 2026 12:09

Preserve API binding configuration with init --from-dash

5cab442

Allow for undefined Previews Base config in API responses

1699d06

GregBrimble force-pushed the guide-setup-of-previews-block branch from f7f4716 to fd42aed Compare September 4, 2026 16:32

This comment was marked as resolved.

Sign in to view

GregBrimble force-pushed the guide-setup-of-previews-block branch from fd42aed to ee8a56c Compare September 4, 2026 18:41

This comment was marked as resolved.

Sign in to view

Support placement in Previews config

7f6ede1

GregBrimble force-pushed the guide-setup-of-previews-block branch 2 times, most recently from de57a51 to ab95ac1 Compare September 4, 2026 18:48

Guide users to set up previews config block when absent and using `…

5057179

…wrangler preview`

GregBrimble force-pushed the guide-setup-of-previews-block branch from ab95ac1 to 5057179 Compare September 4, 2026 19:50

Uh oh!

Conversation

GregBrimble commented Sep 2, 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 2, 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 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

pkg-pr-new Bot commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

devin-ai-integration Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

GregBrimble commented Sep 2, 2026 •

edited by devin-ai-integration Bot

Loading

changeset-bot Bot commented Sep 2, 2026 •

edited

Loading

workers-devprod commented Sep 2, 2026 •

edited

Loading

devin-ai-integration Bot left a comment •

edited

Loading

pkg-pr-new Bot commented Sep 2, 2026 •

edited

Loading

devin-ai-integration Bot left a comment •

edited

Loading

devin-ai-integration Bot Sep 4, 2026 •

edited

Loading