add remoteBindings option to vite plugin

Author: dario-piotrowicz

.changeset/cyan-pets-prove.md

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

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"
+	}
+}

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 }>;

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" }
+	]
+}

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"]
+}

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"]
+}

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,
+		}),
+	],
+});

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,
+	},
+}

packages/vite-plugin-cloudflare/e2e/remote-bindings.test.ts

@@ -138,3 +138,24 @@ 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) => {
+		test.skipIf(isBuildAndPreviewOnWindows(command))(
+			"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");
+			}
+		);
+	});
+});

packages/vite-plugin-cloudflare/src/miniflare-options.ts

@@ -413,13 +413,16 @@ export async function getDevMiniflareOptions(config: {
 								: undefined;
 
 							const remoteProxySessionData =
-								await maybeStartOrUpdateRemoteProxySession(
-									{
-										name: workerConfig.name,
-										bindings: bindings ?? {},
-									},
-									preExistingRemoteProxySession ?? null
-								);
+								!resolvedPluginConfig.remoteBindingsEnabled
+									? // 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(
@@ -739,13 +742,16 @@ export async function getPreviewMiniflareOptions(config: {
 					: undefined;
 
 				const remoteProxySessionData =
-					await maybeStartOrUpdateRemoteProxySession(
-						{
-							name: workerConfig.name,
-							bindings: bindings ?? {},
-						},
-						preExistingRemoteProxySessionData ?? null
-					);
+					!resolvedPluginConfig.remoteBindingsEnabled
+						? // 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(