enable environment targeting in config patching with wrangler deploy --x-remote-diff-check (#11160)

* enable environment targeting in `wrangler deploy --x-remote-diff-check`

* remove `isTopLevelOnly` logic

Author: dario-piotrowicz

.changeset/dark-bars-turn.md

@@ -0,0 +1,7 @@
+---
+"wrangler": patch
+---
+
+Allows auto-update of the local Wrangler configuration file to match remote configuration when running `wrangler deploy --env <TARGET_ENV>`
+
+When running `wrangler deploy`, with `--x-remote-diff-check` and after cancelling the deployment due to destructive changes present in the local config file, Wrangler offers to update the Wrangler configuration file to match the remote configuration. This wasn't however enabled when a target environment was specified (via the `--env|-e` flag). Now this will also apply when an environment is targeted.

packages/workers-utils/src/config/config.ts

@@ -16,7 +16,7 @@ import type {
  * Notes:
  *
  * - Fields that are only specified in `ConfigFields` and not `Environment` can only appear
- * in the top level config and should not appear in any environments.
+ *   in the top level config and should not appear in any environments.
  * - Fields that are specified in `PagesConfigFields` are only relevant for Pages projects
  * - All top level fields in config and environments are optional in the Wrangler configuration file.
  *

packages/wrangler/src/__tests__/deploy.test.ts

@@ -14934,7 +14934,7 @@ export default{
 				script: {
 					created_on: "2025-08-07T09:34:47.846308Z",
 					modified_on: "2025-08-08T10:48:12.688997Z",
-					id: "silent-firefly-dbe3",
+					id: "my-worker-id",
 					observability: { enabled: true, head_sampling_rate: 1 },
 					compatibility_date: "2024-04-24",
 				},
@@ -15000,7 +15000,7 @@ export default{
 				script: {
 					created_on: "2025-08-07T09:34:47.846308Z",
 					modified_on: "2025-08-08T10:48:12.688997Z",
-					id: "silent-firefly-dbe3",
+					id: "my-worker-id",
 					observability: { enabled: true, head_sampling_rate: 1 },
 					compatibility_date: "2024-04-24",
 				},
@@ -15065,7 +15065,7 @@ export default{
 				script: {
 					created_on: "2025-08-07T09:34:47.846308Z",
 					modified_on: "2025-08-08T10:48:12.688997Z",
-					id: "silent-firefly-dbe3",
+					id: "my-worker-id",
 					observability: { enabled: true, head_sampling_rate: 1 },
 					compatibility_date: "2024-04-24",
 				},

packages/wrangler/src/__tests__/deploy/get-config-patch.test.ts

@@ -250,4 +250,56 @@ describe("getConfigPatch", () => {
 			},
 		});
 	});
+
+	test("configs get added/set to a target environment", () => {
+		/*
+			Note: in the remote configuration we don't know if a value is actually there because
+			      inherited from the top level or not, so to be safe we just add it to the target
+				  environment, this applies to all configurations besides the ones that are only
+				  allowed at the top level
+			*/
+		expect(
+			getConfigPatch(
+				{
+					preview_urls: {
+						__old: false,
+						__new: true,
+					},
+					kv_namespaces: [
+						[
+							"-",
+							{
+								id: "<my-kv>",
+								binding: "MY_KV",
+							},
+						],
+						[
+							"-",
+							{
+								id: "<my-kv-a>",
+								binding: "MY_KV_A",
+							},
+						],
+					],
+				},
+				"staging"
+			)
+		).toEqual({
+			env: {
+				staging: {
+					kv_namespaces: [
+						{
+							binding: "MY_KV",
+							id: "<my-kv>",
+						},
+						{
+							binding: "MY_KV_A",
+							id: "<my-kv-a>",
+						},
+					],
+					preview_urls: false,
+				},
+			},
+		});
+	});
 });

packages/wrangler/src/__tests__/deploy/get-remote-config-diff.test.ts

@@ -19,7 +19,7 @@ describe("getRemoteConfigsDiff", () => {
 	it("should handle a very simple diffing scenario (no diffs, random order)", () => {
 		const { diff, nonDestructive } = getRemoteConfigDiff(
 			{
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				main: "/tmp/src/index.js",
 				workers_dev: true,
 				preview_urls: true,
@@ -31,7 +31,7 @@ describe("getRemoteConfigsDiff", () => {
 				observability: { enabled: true, head_sampling_rate: 1 },
 			},
 			{
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				workers_dev: undefined,
 				placement: undefined,
 				compatibility_date: "2025-07-08",
@@ -50,14 +50,14 @@ describe("getRemoteConfigsDiff", () => {
 	it("should handle a very simple diffing scenario where there is only an addition to an array (specifically in `kv_namespaces`)", () => {
 		const { diff, nonDestructive } = getRemoteConfigDiff(
 			{
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				main: "/tmp/src/index.js",
 				workers_dev: true,
 				kv_namespaces: [{ binding: "MY_KV", id: "<kv-id>" }],
 				preview_urls: true,
 			},
 			{
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				main: "/tmp/src/index.js",
 				workers_dev: true,
 				preview_urls: true,
@@ -83,7 +83,7 @@ describe("getRemoteConfigsDiff", () => {
 	it("should handle a very simple diffing scenario (some diffs, random order)", () => {
 		const { diff, nonDestructive } = getRemoteConfigDiff(
 			{
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				main: "/tmp/src/index.js",
 				workers_dev: true,
 				preview_urls: true,
@@ -98,7 +98,7 @@ describe("getRemoteConfigsDiff", () => {
 				compatibility_date: "2025-07-09",
 				main: "/tmp/src/index.js",
 				compatibility_flags: [],
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				workers_dev: true,
 				limits: undefined,
 				placement: undefined,
@@ -121,7 +121,7 @@ describe("getRemoteConfigsDiff", () => {
 	it("should handle a diffing scenario with only additions", () => {
 		const { diff, nonDestructive } = getRemoteConfigDiff(
 			{
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				main: "/tmp/src/index.js",
 				workers_dev: true,
 				preview_urls: true,
@@ -134,7 +134,7 @@ describe("getRemoteConfigsDiff", () => {
 				kv_namespaces: [{ binding: "MY_KV", id: "my-kv-123" }],
 			},
 			{
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				main: "src/index.js",
 				compatibility_date: "2025-07-08",
 				account_id: "account-id-123",
@@ -163,7 +163,7 @@ describe("getRemoteConfigsDiff", () => {
 	it("should handle a diffing scenario with only deletions", () => {
 		const { diff, nonDestructive } = getRemoteConfigDiff(
 			{
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				main: "/tmp/src/index.js",
 				workers_dev: true,
 				preview_urls: false,
@@ -176,7 +176,7 @@ describe("getRemoteConfigsDiff", () => {
 				kv_namespaces: [{ binding: "MY_KV", id: "my-kv-123" }],
 			},
 			{
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				main: "/tmp/src/index.js",
 				workers_dev: true,
 				preview_urls: false,
@@ -206,7 +206,7 @@ describe("getRemoteConfigsDiff", () => {
 	it("should handle a diffing scenario with modifications and removals", () => {
 		const { diff, nonDestructive } = getRemoteConfigDiff(
 			{
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				main: "/tmp/src/index.js",
 				workers_dev: true,
 				preview_urls: true,
@@ -219,7 +219,7 @@ describe("getRemoteConfigsDiff", () => {
 				kv_namespaces: [{ binding: "MY_KV", id: "my-kv-123" }],
 			},
 			{
-				name: "silent-firefly-dbe3",
+				name: "my-worker-id",
 				main: "src/index.js",
 				compatibility_date: "2025-07-09",
 				observability: {

packages/wrangler/src/deploy/config-diffs.ts

@@ -290,13 +290,23 @@ function orderObjectFields<T extends Record<string, unknown>>(
  * Given a config diff generates a patch object that can be passed to `experimental_patchConfig` to revert the
  * changes in the config object that are described by the config diff.
  *
+ * If the config is for a specific target environment, only the environment config object will be targeted for the patch.
+ *
  * @param configDiff The target config diff
+ * @param targetEnvironment the target environment if any
  * @returns The patch object to pass to `experimental_patchConfig` to revert the changes
  */
-export function getConfigPatch(configDiff: ConfigDiff["diff"]): RawConfig {
+export function getConfigPatch(
+	configDiff: ConfigDiff["diff"],
+	targetEnvironment?: string | undefined
+): RawConfig {
 	const patchObj: RawConfig = {};
 
-	populateConfigPatch(configDiff, patchObj as Record<string, JsonLike>);
+	populateConfigPatch(
+		configDiff,
+		patchObj as Record<string, JsonLike>,
+		targetEnvironment
+	);
 
 	return patchObj;
 }
@@ -306,10 +316,12 @@ export function getConfigPatch(configDiff: ConfigDiff["diff"]): RawConfig {
  *
  * @param diff The current section of the config diff that is being analyzed
  * @param patchObj The current section of the patch object that is being populated
+ * @param targetEnvironment the target environment if any
  */
 function populateConfigPatch(
 	diff: JsonLike,
-	patchObj: Record<string, JsonLike> | JsonLike[]
+	patchObj: Record<string, JsonLike> | JsonLike[],
+	targetEnvironment?: string
 ): void {
 	if (!diff || typeof diff !== "object") {
 		return;
@@ -324,7 +336,7 @@ function populateConfigPatch(
 
 	// We know that patchObj is not an array here
 	assert(!Array.isArray(patchObj));
-	return populateConfigPatchObject(diff, patchObj);
+	return populateConfigPatchObject(diff, patchObj, targetEnvironment);
 }
 
 /**
@@ -371,34 +383,64 @@ function populateConfigPatchArray(diff: JsonLike[], patchArray: JsonLike[]) {
  *
  * @param diff The current section of the config diff that is being analyzed
  * @param patchObj The current section of the patch object that is being populated
+ * @param targetEnvironment the target environment if any
  */
 function populateConfigPatchObject(
 	diff: { [id: string]: JsonLike },
-	patchObj: Record<string, JsonLike>
+	patchObj: Record<string, JsonLike>,
+	targetEnvironment?: string
 ) {
+	const getEnvObj = (targetEnv: string) => {
+		patchObj.env ??= {};
+		const patchObjEnv = patchObj.env as Record<string, Record<string, unknown>>;
+		patchObjEnv[targetEnv] ??= {};
+		return patchObjEnv[targetEnv];
+	};
 	Object.keys(diff)
 		.filter((key) => diff[key] && typeof diff[key] === "object")
 		.forEach((key) => {
 			if (isModifiedDiffValue(diff[key])) {
-				patchObj[key] = diff[key].__old;
+				if (targetEnvironment) {
+					getEnvObj(targetEnvironment)[key] = diff[key].__old;
+				} else {
+					patchObj[key] = diff[key].__old;
+				}
 				return;
 			}
 
-			patchObj[key] = Array.isArray(diff[key]) ? [] : {};
+			if (targetEnvironment) {
+				getEnvObj(targetEnvironment)[key] ??= Array.isArray(diff[key])
+					? []
+					: {};
+			} else {
+				patchObj[key] ??= Array.isArray(diff[key]) ? [] : {};
+			}
 
 			Object.entries(diff[key] as Record<string, JsonLike>).forEach(
 				([entryKey, entryValue]) => {
 					if (entryKey.endsWith("__deleted")) {
-						(patchObj[key] as Record<string, unknown>)[
-							entryKey.replace("__deleted", "")
-						] = entryValue;
+						let patchObjectToUpdate = patchObj[key] as Record<string, unknown>;
+						if (targetEnvironment) {
+							const envObj = getEnvObj(targetEnvironment);
+							envObj[key] ??= {};
+							patchObjectToUpdate = envObj[key] as Record<string, unknown>;
+						}
+						patchObjectToUpdate[entryKey.replace("__deleted", "")] = entryValue;
 						return;
 					}
 				}
 			);
 
 			if (diff[key] && typeof diff[key] === "object") {
-				populateConfigPatch(diff[key], patchObj[key]);
+				populateConfigPatch(
+					diff[key],
+					(targetEnvironment
+						? getEnvObj(targetEnvironment)[key]
+						: patchObj[key]) as Record<string, JsonLike> | JsonLike[]
+					// Note: we are not passing the target environment since in the recursive calls
+					//       we are already one level deep and dealing with the environment specific
+					//       patch object
+				);
 				return;
 			}
 		});

packages/wrangler/src/deploy/deploy.ts

@@ -432,22 +432,19 @@ export default async function deploy(props: Props): Promise<{
 								config.userConfigPath &&
 								/\.jsonc?$/.test(config.userConfigPath)
 							) {
-								const targetingEnvironment = !!props.env;
-
 								if (
-									// TODO: Currently if the user is targeting an environment we don't offer them to update
-									// their config file since that is fairly nuanced, we should also support environments
-									// (the best we can) here
-									!targetingEnvironment &&
-									(await confirm(
+									await confirm(
 										"Would you like to update the local config file with the remote values?",
 										{
 											defaultValue: true,
 											fallbackValue: true,
 										}
-									))
+									)
 								) {
-									const patchObj: RawConfig = getConfigPatch(configDiff.diff);
+									const patchObj: RawConfig = getConfigPatch(
+										configDiff.diff,
+										props.env
+									);
 
 									experimental_patchConfig(
 										config.userConfigPath,