Various fixes/improvements around remote bindings being used as local (#11162)

dario-piotrowicz · penalosa · web-flow · commit c3ed5314c831 · 2025-11-05T14:36:10.000Z
* Fix the fact that some remote bindings, such as AI still work as remote under `wrangler dev --local`

* Fix bindings with `remote: true` being logged as `remote` when run via `wrangler dev --local`

* remote outdated tsdoc param

* Update the description of the `--local` flag for the `wrangler dev` command to clarify that it disables remote bindings, also un-deprecate and un-hide it

* make sure that `getPlatformProxy` and the vite plugin have a `remoteBindings` option that can be used to disable remote bindings


---------

Co-authored-by: Somhairle MacLeòid &lt;smacleod@cloudflare.com&gt;
diff --git a/.changeset/cyan-pets-prove.md b/.changeset/cyan-pets-prove.md
@@ -0,0 +1,5 @@
+---
+"@cloudflare/vite-plugin": minor
+---
+
+add a `remoteBindings` option to allow the disabling of remote bindings
diff --git a/.changeset/modern-foxes-dream.md b/.changeset/modern-foxes-dream.md
@@ -0,0 +1,5 @@
+---
+"wrangler": minor
+---
+
+add a `remoteBindings` option to `getPlatformProxy` to allow the disabling of remote bindings
diff --git a/.changeset/shy-teams-appear.md b/.changeset/shy-teams-appear.md
@@ -0,0 +1,5 @@
+---
+"wrangler": patch
+---
+
+Update the description of the `--local` flag for the `wrangler dev` command to clarify that it disables remote bindings, also un-deprecate and un-hide it
diff --git a/.changeset/thirty-lights-build.md b/.changeset/thirty-lights-build.md
@@ -0,0 +1,5 @@
+---
+"wrangler": patch
+---
+
+Fix bindings with `remote: true` being logged as `remote` when run via `wrangler dev --local`
diff --git a/fixtures/get-platform-proxy-remote-bindings/tests/remote-bindings-false.test.ts b/fixtures/get-platform-proxy-remote-bindings/tests/remote-bindings-false.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, test } from "vitest";
+import { getPlatformProxy } from "wrangler";
+import type { Ai } from "@cloudflare/workers-types/experimental";
+
+describe("getPlatformProxy - remote bindings with remoteBindings: false", () => {
+	test("getPlatformProxy works with remote bindings", async () => {
+		const { env, dispose } = await getPlatformProxy<{
+			AI: Ai;
+		}>({
+			configPath: "./wrangler.remote-bindings-false.jsonc",
+			remoteBindings: false,
+		});
+
+		await expect(
+			env.AI.run("@cf/meta/llama-3.1-8b-instruct-fp8", {
+				messages: [],
+			})
+		).rejects.toThrowErrorMatchingInlineSnapshot(
+			`[Error: Binding AI needs to be run remotely]`
+		);
+
+		await dispose();
+	});
+});
diff --git a/fixtures/get-platform-proxy-remote-bindings/wrangler.remote-bindings-false.jsonc b/fixtures/get-platform-proxy-remote-bindings/wrangler.remote-bindings-false.jsonc
@@ -0,0 +1,8 @@
+{
+	"name": "get-platform-proxy-remote-bindings-with-local-bindings-only-test",
+	"compatibility_date": "2025-05-07",
+	"ai": {
+		"binding": "AI",
+		"remote": true,
+	},
+}
diff --git a/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/package.json b/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/package.json
@@ -0,0 +1,25 @@
+{
+	"name": "@cloudflare/vite-plugin-e2e-remote-bindings-disabled",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "vite build",
+		"buildAndPreview": "vite build && vite preview",
+		"dev": "vite",
+		"lint": "eslint .",
+		"preview": "vite preview"
+	},
+	"devDependencies": {
+		"@cloudflare/vite-plugin": "*",
+		"@cloudflare/workers-types": "^4.20250204.0",
+		"@eslint/js": "^9.19.0",
+		"eslint": "^9.19.0",
+		"eslint-plugin-react-hooks": "^5.0.0",
+		"eslint-plugin-react-refresh": "^0.4.18",
+		"globals": "^15.14.0",
+		"typescript": "~5.7.2",
+		"typescript-eslint": "^8.22.0",
+		"vite": "^6.1.0"
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/src/index.ts b/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/src/index.ts
@@ -0,0 +1,11 @@
+export default {
+	async fetch(_req, env) {
+		const content = await env.AI.run("@cf/meta/llama-2-7b-chat-fp16", {
+			messages: [],
+		});
+
+		return Response.json({
+			response: content.response,
+		});
+	},
+} satisfies ExportedHandler<{ AI: Ai }>;
diff --git a/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/tsconfig.json b/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/tsconfig.json
@@ -0,0 +1,7 @@
+{
+	"files": [],
+	"references": [
+		{ "path": "./tsconfig.node.json" },
+		{ "path": "./tsconfig.worker.json" }
+	]
+}
diff --git a/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/tsconfig.node.json b/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/tsconfig.node.json
@@ -0,0 +1,24 @@
+{
+	"compilerOptions": {
+		"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+		"target": "ES2022",
+		"lib": ["ES2023"],
+		"module": "ESNext",
+		"skipLibCheck": true,
+
+		/* Bundler mode */
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"isolatedModules": true,
+		"moduleDetection": "force",
+		"noEmit": true,
+
+		/* Linting */
+		"strict": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedSideEffectImports": true
+	},
+	"include": ["vite.config.ts"]
+}
diff --git a/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/tsconfig.worker.json b/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/tsconfig.worker.json
@@ -0,0 +1,8 @@
+{
+	"extends": "./tsconfig.node.json",
+	"compilerOptions": {
+		"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.worker.tsbuildinfo",
+		"types": ["@cloudflare/workers-types/2023-07-01", "vite/client"]
+	},
+	"include": ["src"]
+}
diff --git a/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/vite.config.ts b/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/vite.config.ts
@@ -0,0 +1,13 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	plugins: [
+		cloudflare({
+			configPath: "./wrangler.jsonc",
+			inspectorPort: false,
+			remoteBindings: false,
+			persistState: false,
+		}),
+	],
+});
diff --git a/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/wrangler.jsonc b/packages/vite-plugin-cloudflare/e2e/fixtures/remote-bindings-disabled/wrangler.jsonc
@@ -0,0 +1,10 @@
+{
+	"name": "cloudflare-vite-e2e-remote-bindings-disabled",
+	"main": "./src/index.ts",
+	"compatibility_date": "2024-12-30",
+	"compatibility_flags": ["nodejs_compat"],
+	"ai": {
+		"binding": "AI",
+		"remote": true,
+	},
+}
diff --git a/packages/vite-plugin-cloudflare/e2e/remote-bindings.test.ts b/packages/vite-plugin-cloudflare/e2e/remote-bindings.test.ts
@@ -138,3 +138,28 @@ if (!process.env.CLOUDFLARE_ACCOUNT_ID || !process.env.CLOUDFLARE_API_TOKEN) {
 			});
 		});
 }
+
+describe("remote bindings disabled", () => {
+	const projectPath = seed("remote-bindings-disabled", "pnpm");
+
+	describe.each(commands)('with "%s" command', (command) => {
+		// On Windows the path for the miniflare dependency gets pretty long and this fails in node < 22.7
+		// (see: https://github.com/shellscape/jsx-email/issues/225#issuecomment-2420567832), so
+		// we need to skip this on windows since in CI we're using node 20
+		// we should look into re-enable this once we can move to a node a newer version of node
+		test.skipIf(process.platform === "win32")(
+			"cannot connect to remote bindings",
+			async ({ expect }) => {
+				const proc = await runLongLived("pnpm", command, projectPath);
+				const url = await waitForReady(proc);
+
+				const response = await fetch(url);
+
+				const responseText = await response.text();
+
+				expect(responseText).toContain("Error");
+				expect(responseText).toContain("Binding AI needs to be run remotely");
+			}
+		);
+	});
+});
diff --git a/packages/vite-plugin-cloudflare/src/miniflare-options.ts b/packages/vite-plugin-cloudflare/src/miniflare-options.ts
@@ -393,13 +393,16 @@ export async function getDevMiniflareOptions(
 								: undefined;
 
 							const remoteProxySessionData =
-								await maybeStartOrUpdateRemoteProxySession(
-									{
-										name: workerConfig.name,
-										bindings: bindings ?? {},
-									},
-									preExistingRemoteProxySession ?? null
-								);
+								!resolvedPluginConfig.remoteBindings
+									? // if remote bindings are not enabled then the proxy session can simply be null
+										null
+									: await maybeStartOrUpdateRemoteProxySession(
+											{
+												name: workerConfig.name,
+												bindings: bindings ?? {},
+											},
+											preExistingRemoteProxySession ?? null
+										);
 
 							if (workerConfig.configPath && remoteProxySessionData) {
 								remoteProxySessionsDataMap.set(
@@ -714,14 +717,16 @@ export async function getPreviewMiniflareOptions(
 					? remoteProxySessionsDataMap.get(workerConfig.configPath)
 					: undefined;
 
-				const remoteProxySessionData =
-					await maybeStartOrUpdateRemoteProxySession(
-						{
-							name: workerConfig.name,
-							bindings: bindings ?? {},
-						},
-						preExistingRemoteProxySessionData ?? null
-					);
+				const remoteProxySessionData = !resolvedPluginConfig.remoteBindings
+					? // if remote bindings are not enabled then the proxy session can simply be null
+						null
+					: await maybeStartOrUpdateRemoteProxySession(
+							{
+								name: workerConfig.name,
+								bindings: bindings ?? {},
+							},
+							preExistingRemoteProxySessionData ?? null
+						);
 
 				if (workerConfig.configPath && remoteProxySessionData) {
 					remoteProxySessionsDataMap.set(
diff --git a/packages/vite-plugin-cloudflare/src/plugin-config.ts b/packages/vite-plugin-cloudflare/src/plugin-config.ts
@@ -41,6 +41,7 @@ export interface PluginConfig extends EntryWorkerConfig {
 	auxiliaryWorkers?: AuxiliaryWorkerConfig[];
 	persistState?: PersistState;
 	inspectorPort?: number | false;
+	remoteBindings?: boolean;
 	experimental?: Experimental;
 }
 
@@ -58,6 +59,7 @@ interface BaseResolvedConfig {
 	persistState: PersistState;
 	inspectorPort: number | false | undefined;
 	experimental: Experimental;
+	remoteBindings: boolean;
 }
 
 export interface AssetsOnlyResolvedConfig extends BaseResolvedConfig {
@@ -123,6 +125,7 @@ export function resolvePluginConfig(
 	if (viteEnv.isPreview) {
 		return {
 			...shared,
+			remoteBindings: pluginConfig.remoteBindings ?? true,
 			type: "preview",
 			workers: getWorkerConfigs(root),
 		};
@@ -151,6 +154,7 @@ export function resolvePluginConfig(
 			cloudflareEnv,
 			config: entryWorkerResolvedConfig.config,
 			configPaths,
+			remoteBindings: pluginConfig.remoteBindings ?? true,
 			rawConfigs: {
 				entryWorker: entryWorkerResolvedConfig,
 			},
@@ -231,6 +235,7 @@ export function resolvePluginConfig(
 		entryWorkerEnvironmentName,
 		nodeJsCompatMap,
 		staticRouting,
+		remoteBindings: pluginConfig.remoteBindings ?? true,
 		rawConfigs: {
 			entryWorker: entryWorkerResolvedConfig,
 			auxiliaryWorkers: auxiliaryWorkersResolvedConfigs,
diff --git a/packages/wrangler/e2e/remote-binding/dev-remote-bindings.test.ts b/packages/wrangler/e2e/remote-binding/dev-remote-bindings.test.ts
@@ -174,30 +174,17 @@ describe.skipIf(!CLOUDFLARE_ACCOUNT_ID)(
 			);
 
 			// This should only include logs from the user Wrangler session (i.e. a single list of attached bindings, and only one ready message)
-			// Logs order are not deterministic, so we match against to possible outputs.
-			const output1 = dedent`
-			Your Worker has access to the following bindings:
-			Binding        Resource      Mode
-			env.AI         AI            remote
-			▲ [WARNING] AI bindings always access remote resources, and so may incur usage charges even in local dev. To suppress this warning, set \`remote: true\` for the binding definition in your configuration file.
-			⎔ Starting local server...
-			[wrangler:info] Ready on http://<HOST>:<PORT>
-			[wrangler:info] GET / 200 OK (TIMINGS)`;
-
-			const output2 = dedent`
-			Your Worker has access to the following bindings:
-			Binding        Resource      Mode
-			env.AI         AI            remote
-			▲ [WARNING] AI bindings always access remote resources, and so may incur usage charges even in local dev. To suppress this warning, set \`remote: true\` for the binding definition in your configuration file.
-			⎔ Starting local server...
-			[wrangler:info] Ready on http://<HOST>:<PORT>
-			[wrangler:info] GET / 200 OK (TIMINGS)`;
-
 			const normalizedOutput = normalizeOutput(worker.currentOutput);
 
-			expect(
-				normalizedOutput === output1 || normalizedOutput === output2
-			).toEqual(true);
+			expect(normalizedOutput).toMatchInlineSnapshot(`
+				"Your Worker has access to the following bindings:
+				Binding        Resource      Mode
+				env.AI         AI            remote
+				▲ [WARNING] AI bindings always access remote resources, and so may incur usage charges even in local dev. To suppress this warning, set \`remote: true\` for the binding definition in your configuration file.
+				⎔ Starting local server...
+				[wrangler:info] Ready on http://<HOST>:<PORT>
+				[wrangler:info] GET / 200 OK (TIMINGS)"
+			`);
 		});
 
 		describe("shows helpful error logs", () => {
diff --git a/packages/wrangler/e2e/remote-binding/start-worker-remote-bindings.test.ts b/packages/wrangler/e2e/remote-binding/start-worker-remote-bindings.test.ts
@@ -124,3 +124,36 @@ describe.skipIf(!CLOUDFLARE_ACCOUNT_ID)("startWorker - remote bindings", () => {
 		await worker.dispose();
 	});
 });
+
+it("doesn't connect to remote bindings when `remote` is set to `false`", async () => {
+	const helper = new WranglerE2ETestHelper();
+	await helper.seed(resolve(__dirname, "./workers"));
+	await helper.seed({
+		"wrangler.json": JSON.stringify({
+			name: "remote-bindings-test",
+			main: "ai.js",
+			compatibility_date: "2025-05-07",
+			ai: {
+				binding: "AI",
+				remote: true,
+			},
+		}),
+	});
+
+	await expect(async () => {
+		const worker = await startWorker({
+			config: `${helper.tmpPath}/wrangler.json`,
+			dev: {
+				inspector: false,
+				server: { port: 0 },
+				remote: false,
+			},
+		});
+
+		await worker.ready;
+
+		await worker.fetch("http://example.com");
+	}).rejects.toThrowErrorMatchingInlineSnapshot(
+		`[Error: Binding AI needs to be run remotely]`
+	);
+});
diff --git a/packages/wrangler/src/__tests__/dev/remote-bindings.test.ts b/packages/wrangler/src/__tests__/dev/remote-bindings.test.ts
@@ -653,6 +653,18 @@ describe("dev with remote bindings", { sequential: true }, () => {
 		await vi.waitFor(() => expect(std.out).toMatch(/Ready/), {
 			timeout: 2_000,
 		});
+		const bindingsPrintStart = std.out.indexOf(
+			"Your Worker has access to the following bindings:"
+		);
+		const bindingsPrintEnd = std.out.indexOf("⎔ Starting local server...") - 1;
+		expect(std.out.slice(bindingsPrintStart, bindingsPrintEnd))
+			.toMatchInlineSnapshot(`
+			"Your Worker has access to the following bindings:
+			Binding                                        Resource          Mode
+			env.KV_LOCAL_BINDING (mock-kv-namespace)       KV Namespace      local
+			env.KV_REMOTE_BINDING (mock-kv-namespace)      KV Namespace      local
+			"
+		`);
 		expect(proxyWorkerBindings).toEqual(undefined);
 		expect(workerOptions).toEqual([
 			expect.objectContaining({
diff --git a/packages/wrangler/src/api/integrations/platform/index.ts b/packages/wrangler/src/api/integrations/platform/index.ts
@@ -85,6 +85,10 @@ export type GetPlatformProxyOptions = {
 	 * If `false` is specified no data is persisted on the filesystem.
 	 */
 	persist?: boolean | { path: string };
+	/**
+	 * Whether remote bindings should be enabled or not (defaults to `true`)
+	 */
+	remoteBindings?: boolean;
 };
 
 /**
@@ -138,7 +142,7 @@ export async function getPlatformProxy<
 	});
 
 	let remoteProxySession: RemoteProxySession | undefined = undefined;
-	if (config.configPath) {
+	if (config.configPath && options.remoteBindings !== false) {
 		remoteProxySession = (
 			(await maybeStartOrUpdateRemoteProxySession({
 				path: config.configPath,
diff --git a/packages/wrangler/src/api/startDevWorker/ConfigController.ts b/packages/wrangler/src/api/startDevWorker/ConfigController.ts
diff --git a/packages/wrangler/src/dev.ts b/packages/wrangler/src/dev.ts
diff --git a/packages/wrangler/src/dev/start-dev.ts b/packages/wrangler/src/dev/start-dev.ts
diff --git a/packages/wrangler/src/utils/print-bindings.ts b/packages/wrangler/src/utils/print-bindings.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@cloudflare/vite-plugin": minor
 +---
++
 +add a `remoteBindings` option to allow the disabling of remote bindings