From 7abe589b1f13903f465dad16f8ab828d89c25c6c Mon Sep 17 00:00:00 2001
From: Patrick O'Donnell <podonnell@cloudflare.com>
Date: Fri, 18 Sep 2026 14:35:39 -0400
Subject: [PATCH] WC-6017 [wrangler] previews: fold in unnecessary warning

---
 .changeset/bright-owls-guide.md                 |  7 +++++++
 packages/wrangler/src/__tests__/preview.test.ts | 12 +++++++-----
 packages/wrangler/src/preview/ensure-config.ts  | 14 ++++++++------
 3 files changed, 22 insertions(+), 11 deletions(-)
 create mode 100644 .changeset/bright-owls-guide.md

diff --git a/.changeset/bright-owls-guide.md b/.changeset/bright-owls-guide.md
new file mode 100644
index 00000000000..45f791324ac
--- /dev/null
+++ b/.changeset/bright-owls-guide.md
@@ -0,0 +1,7 @@
+---
+"wrangler": patch
+---
+
+Improve `wrangler preview` onboarding guidance
+
+Wrangler now displays placeholder replacement guidance directly beneath the suggested Preview configuration instead of as a separate warning. JSON output continues to include the guidance in its structured onboarding messages.
diff --git a/packages/wrangler/src/__tests__/preview.test.ts b/packages/wrangler/src/__tests__/preview.test.ts
index 2f450bcfa59..40df213851b 100644
--- a/packages/wrangler/src/__tests__/preview.test.ts
+++ b/packages/wrangler/src/__tests__/preview.test.ts
@@ -2140,7 +2140,10 @@ describe("wrangler preview", () => {
 			expect((thrown as Error).message).toContain("IMPORTANT_BINDING");
 			expect((thrown as Error).message).toContain('"id": "<REPLACE_ME>"');
 			expect((thrown as Error).message).not.toContain("kv-id-123");
-			expect(std.warn).toContain(
+			expect((thrown as Error).message).toMatch(
+				/}\n\nReplace each <REPLACE_ME> placeholder with a Preview-safe value\. Do not use production resources unless you intend for this Preview to access them\.$/
+			);
+			expect(std.warn).not.toContain(
 				"Replace each <REPLACE_ME> placeholder with a Preview-safe value. Do not use production resources unless you intend for this Preview to access them."
 			);
 		});
@@ -2285,12 +2288,11 @@ describe("wrangler preview", () => {
 				.filter(
 					(message) =>
 						typeof message === "string" &&
-						(message.startsWith(
+						message.startsWith(
 							"These settings have limitations in Worker Previews"
-						) ||
-							message.startsWith("Replace each <REPLACE_ME>"))
+						)
 				);
-			expect(conversionWarnings).toHaveLength(2);
+			expect(conversionWarnings).toHaveLength(1);
 		});
 
 		test("should not warn about top-level bindings when they are present in local previews config", async ({
diff --git a/packages/wrangler/src/preview/ensure-config.ts b/packages/wrangler/src/preview/ensure-config.ts
index dba804b5e95..fd74bbc0989 100644
--- a/packages/wrangler/src/preview/ensure-config.ts
+++ b/packages/wrangler/src/preview/ensure-config.ts
@@ -143,12 +143,6 @@ export async function ensurePreviewsConfig(
 			...selectedConversion.blockingDeploymentMessages,
 		]),
 	];
-	if (!hasPreviewBase && containsGeneratedPlaceholder(proposedConfig)) {
-		conversionMessages.push(
-			"Replace each <REPLACE_ME> placeholder with a Preview-safe value. Do not use production resources unless you intend for this Preview to access them."
-		);
-	}
-
 	const hasEmptyProposedConfig = Object.keys(proposedConfig).length === 0;
 	const hasBlockingDeploymentMessages =
 		selectedConversion.blockingDeploymentMessages.length > 0;
@@ -160,6 +154,14 @@ export async function ensurePreviewsConfig(
 				: "Your Wrangler configuration is missing a `previews` block. Add the following to your configuration file:",
 		formattedProposedConfig,
 	];
+	if (!hasPreviewBase && containsGeneratedPlaceholder(proposedConfig)) {
+		const replacementMessage =
+			"Replace each <REPLACE_ME> placeholder with a Preview-safe value. Do not use production resources unless you intend for this Preview to access them.";
+		missingPreviewsConfigParagraphs.push(`\n${replacementMessage}`);
+		if (args.json) {
+			conversionMessages.push(replacementMessage);
+		}
+	}
 	if (hasEmptyProposedConfig && conversionMessages.length === 0) {
 		missingPreviewsConfigParagraphs.push(
 			"To create or update a Preview with `npx wrangler preview`, your Wrangler configuration must include a `previews` block. The block can be empty. Assets, compatibility settings, migrations, and placement stay at the top level and do not need to be added to `previews`.\nLearn more: https://developers.cloudflare.com/workers/previews/configuration/#wrangler-configuration-file"