[vite-plugin] improve inspector port handling (#8680)

* [vite-plugin] fix: make sure that the plugin keeps looking for available inspector ports by default

* [vite-plugin] fix: make sure that users can use inspector port `0` to use a random port

* Update packages/vite-plugin-cloudflare/README.md

Co-authored-by: James Opstad <[email protected]>

* move `resolvedInspectorPort` inside `cloudflare` function

* resolve inspector port in configure server

* remove global `resolvedInspectorPort` variable

* Revert "remove global `resolvedInspectorPort` variable"

This reverts commit 8382228.

* remove global `resolvedInspectorPort` variable (and resolve inspector port id in debug middleware)

* improve code and warn when 9229 is not available

* remove unused imports

* remove useless line of code

* Update packages/vite-plugin-cloudflare/src/index.ts

Co-authored-by: James Opstad <[email protected]>

---------

Co-authored-by: James Opstad <[email protected]>

Author: dario-piotrowicz

.changeset/hip-parents-shave.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/vite-plugin": patch
+---
+
+fix: make sure that users can specify inspector port `0` to use a random port

.changeset/warm-mammals-invent.md

@@ -0,0 +1,9 @@
+---
+"@cloudflare/vite-plugin": patch
+---
+
+fix: make sure that the plugin keeps looking for available inspector ports by default
+
+this change updates the plugin so that if an inspector port is not specified and the
+default inspector port (9229) is not available it keeps looking for other available
+port instead of crashing

packages/vite-plugin-cloudflare/README.md

@@ -376,7 +376,7 @@ It accepts an optional `PluginConfig` parameter.
 
 - `inspectorPort?: number | false`
 
-  Optional inspector port to use for debugging your workers, for more details on debugging see the [devtools section](#devtools). Can be set to `false` to disable the debugging inspector altogether. Defaults to `9229`.
+  Optional inspector port to use for debugging your workers, for more details on debugging see the [devtools section](#devtools). By default the vite plugin will attempt to use the first available port it can find starting at `9229`.
 
 > [!NOTE]
 > When running `wrangler deploy`, only your main (entry) Worker will be deployed.

packages/vite-plugin-cloudflare/package.json

@@ -44,6 +44,7 @@
 	"dependencies": {
 		"@cloudflare/unenv-preset": "workspace:*",
 		"@hattip/adapter-node": "^0.0.49",
+		"get-port": "^7.1.0",
 		"miniflare": "workspace:*",
 		"picocolors": "^1.1.1",
 		"tinyglobby": "^0.2.12",

packages/vite-plugin-cloudflare/src/index.ts

@@ -5,6 +5,7 @@ import * as path from "node:path";
 import { createMiddleware } from "@hattip/adapter-node";
 import MagicString from "magic-string";
 import { Miniflare } from "miniflare";
+import colors from "picocolors";
 import * as vite from "vite";
 import {
 	createModuleReference,
@@ -40,6 +41,7 @@ import { resolvePluginConfig } from "./plugin-config";
 import { additionalModuleGlobalRE } from "./shared";
 import {
 	cleanUrl,
+	getFirstAvailablePort,
 	getOutputDirectory,
 	getRouterWorker,
 	toMiniflareRequest,
@@ -315,13 +317,26 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 					"Unexpected error: No Vite HTTP server"
 				);
 
+				const inputInspectorPort = await getInputInspectorPortOption(
+					pluginConfig,
+					viteDevServer
+				);
+
 				if (miniflare) {
 					await miniflare.setOptions(
-						getDevMiniflareOptions(resolvedPluginConfig, viteDevServer)
+						getDevMiniflareOptions(
+							resolvedPluginConfig,
+							viteDevServer,
+							inputInspectorPort
+						)
 					);
 				} else {
 					miniflare = new Miniflare(
-						getDevMiniflareOptions(resolvedPluginConfig, viteDevServer)
+						getDevMiniflareOptions(
+							resolvedPluginConfig,
+							viteDevServer,
+							inputInspectorPort
+						)
 					);
 				}
 
@@ -352,15 +367,20 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 					});
 				};
 			},
-			configurePreviewServer(vitePreviewServer) {
+			async configurePreviewServer(vitePreviewServer) {
 				const workerConfigs = getWorkerConfigs(vitePreviewServer.config.root);
 
+				const inputInspectorPort = await getInputInspectorPortOption(
+					pluginConfig,
+					vitePreviewServer
+				);
+
 				const miniflare = new Miniflare(
 					getPreviewMiniflareOptions(
 						vitePreviewServer,
 						workerConfigs,
 						pluginConfig.persistState ?? true,
-						pluginConfig.inspectorPort
+						inputInspectorPort
 					)
 				);
 
@@ -612,7 +632,7 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 			configureServer(viteDevServer) {
 				if (
 					resolvedPluginConfig.type === "workers" &&
-					resolvedPluginConfig.inspectorPort !== false
+					pluginConfig.inspectorPort !== false
 				) {
 					addDebugToVitePrintUrls(viteDevServer);
 				}
@@ -624,22 +644,18 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 								(worker) => worker.name
 							);
 
-				viteDevServer.middlewares.use((req, res, next) => {
-					if (
-						req.url === debuggingPath &&
-						resolvedPluginConfig.inspectorPort !== false
-					) {
-						const html = getDebugPathHtml(
-							workerNames,
-							resolvedPluginConfig.inspectorPort
-						);
+				viteDevServer.middlewares.use(async (req, res, next) => {
+					const resolvedInspectorPort =
+						await getResolvedInspectorPort(pluginConfig);
+					if (req.url === debuggingPath && resolvedInspectorPort) {
+						const html = getDebugPathHtml(workerNames, resolvedInspectorPort);
 						res.setHeader("Content-Type", "text/html");
 						return res.end(html);
 					}
 					next();
 				});
 			},
-			configurePreviewServer(vitePreviewServer) {
+			async configurePreviewServer(vitePreviewServer) {
 				const workerConfigs = getWorkerConfigs(vitePreviewServer.config.root);
 
 				if (workerConfigs.length >= 1 && pluginConfig.inspectorPort !== false) {
@@ -651,15 +667,12 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 					return worker.name;
 				});
 
-				vitePreviewServer.middlewares.use((req, res, next) => {
-					if (
-						req.url === debuggingPath &&
-						pluginConfig.inspectorPort !== false
-					) {
-						const html = getDebugPathHtml(
-							workerNames,
-							pluginConfig.inspectorPort ?? DEFAULT_INSPECTOR_PORT
-						);
+				vitePreviewServer.middlewares.use(async (req, res, next) => {
+					const resolvedInspectorPort =
+						await getResolvedInspectorPort(pluginConfig);
+
+					if (req.url === debuggingPath && resolvedInspectorPort) {
+						const html = getDebugPathHtml(workerNames, resolvedInspectorPort);
 						res.setHeader("Content-Type", "text/html");
 						return res.end(html);
 					}
@@ -751,6 +764,49 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 	}
 }
 
+/**
+ * Gets the inspector port option that should be passed to miniflare based on the user's plugin config
+ *
+ * @param pluginConfig the user plugin configs
+ * @param viteServer the vite (dev or preview) server
+ * @returns the inspector port to require from miniflare or false if debugging is disabled
+ */
+async function getInputInspectorPortOption(
+	pluginConfig: PluginConfig,
+	viteServer: vite.ViteDevServer | vite.PreviewServer
+) {
+	const inputInspectorPort =
+		pluginConfig.inspectorPort ??
+		(await getFirstAvailablePort(DEFAULT_INSPECTOR_PORT));
+
+	if (
+		pluginConfig.inspectorPort === undefined &&
+		inputInspectorPort !== DEFAULT_INSPECTOR_PORT
+	) {
+		viteServer.config.logger.warn(
+			colors.dim(
+				`Default inspector port ${DEFAULT_INSPECTOR_PORT} not available, using ${inputInspectorPort} instead\n`
+			)
+		);
+	}
+
+	return inputInspectorPort;
+}
+
+/**
+ * Gets the resolved port of the inspector provided by miniflare
+ *
+ * @param pluginConfig the user's plugin configuration
+ * @returns the resolved port of null if the user opted out of debugging
+ */
+async function getResolvedInspectorPort(pluginConfig: PluginConfig) {
+	if (miniflare && pluginConfig.inspectorPort !== false) {
+		const miniflareInspectorUrl = await miniflare.getInspectorURL();
+		return Number.parseInt(miniflareInspectorUrl.port);
+	}
+	return null;
+}
+
 /**
  * Gets the content of a the potential `.dev.vars` target file
  *

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

@@ -16,7 +16,6 @@ import { getAssetsConfig } from "./asset-config";
 import {
 	ASSET_WORKER_NAME,
 	ASSET_WORKERS_COMPATIBILITY_DATE,
-	DEFAULT_INSPECTOR_PORT,
 	ROUTER_WORKER_NAME,
 } from "./constants";
 import { additionalModuleRE } from "./shared";
@@ -192,7 +191,8 @@ function getEntryWorkerConfig(
 
 export function getDevMiniflareOptions(
 	resolvedPluginConfig: ResolvedPluginConfig,
-	viteDevServer: vite.ViteDevServer
+	viteDevServer: vite.ViteDevServer,
+	inspectorPort: number | false
 ): MiniflareOptions {
 	const resolvedViteConfig = viteDevServer.config;
 	const entryWorkerConfig = getEntryWorkerConfig(resolvedPluginConfig);
@@ -298,8 +298,7 @@ export function getDevMiniflareOptions(
 							worker: {
 								...workerOptions,
 								name: workerOptions.name ?? workerConfig.name,
-								unsafeInspectorProxy:
-									resolvedPluginConfig.inspectorPort !== false,
+								unsafeInspectorProxy: inspectorPort !== false,
 								modulesRoot: miniflareModulesRoot,
 								unsafeEvalBinding: "__VITE_UNSAFE_EVAL__",
 								serviceBindings: {
@@ -370,8 +369,8 @@ export function getDevMiniflareOptions(
 
 	return {
 		log: logger,
-		inspectorPort: resolvedPluginConfig.inspectorPort || undefined,
-		unsafeInspectorProxy: resolvedPluginConfig.inspectorPort !== false,
+		inspectorPort: inspectorPort === false ? undefined : inspectorPort,
+		unsafeInspectorProxy: inspectorPort !== false,
 		handleRuntimeStdio(stdout, stderr) {
 			const decoder = new TextDecoder();
 			stdout.forEach((data) => logger.info(decoder.decode(data)));
@@ -530,7 +529,7 @@ export function getPreviewMiniflareOptions(
 	vitePreviewServer: vite.PreviewServer,
 	workerConfigs: Unstable_Config[],
 	persistState: PersistState,
-	inspectorPort: number | false = DEFAULT_INSPECTOR_PORT
+	inspectorPort: number | false
 ): MiniflareOptions {
 	const resolvedViteConfig = vitePreviewServer.config;
 	const workers: Array<WorkerOptions> = workerConfigs.flatMap((config) => {
@@ -558,7 +557,7 @@ export function getPreviewMiniflareOptions(
 
 	return {
 		log: logger,
-		inspectorPort: inspectorPort || undefined,
+		inspectorPort: inspectorPort === false ? undefined : inspectorPort,
 		unsafeInspectorProxy: inspectorPort !== false,
 		handleRuntimeStdio(stdout, stderr) {
 			const decoder = new TextDecoder();

packages/vite-plugin-cloudflare/src/plugin-config.ts

@@ -1,7 +1,6 @@
 import assert from "node:assert";
 import * as path from "node:path";
 import * as vite from "vite";
-import { DEFAULT_INSPECTOR_PORT } from "./constants";
 import {
 	getValidatedWranglerConfigPath,
 	getWorkerConfig,
@@ -53,7 +52,6 @@ interface BasePluginConfig {
 	configPaths: Set<string>;
 	persistState: PersistState;
 	cloudflareEnv: string | undefined;
-	inspectorPort: number | false;
 	experimental: {
 		/** Experimental support for handling the _headers and _redirects files during Vite dev mode. */
 		headersAndRedirectsDevModeSupport?: boolean;
@@ -92,7 +90,6 @@ export function resolvePluginConfig(
 ): ResolvedPluginConfig {
 	const configPaths = new Set<string>();
 	const persistState = pluginConfig.persistState ?? true;
-	const inspectorPort = pluginConfig.inspectorPort ?? DEFAULT_INSPECTOR_PORT;
 	const experimental = pluginConfig.experimental ?? {};
 	const root = userConfig.root ? path.resolve(userConfig.root) : process.cwd();
 	const { CLOUDFLARE_ENV: cloudflareEnv } = vite.loadEnv(
@@ -120,7 +117,6 @@ export function resolvePluginConfig(
 			type: "assets-only",
 			config: entryWorkerResolvedConfig.config,
 			configPaths,
-			inspectorPort,
 			persistState,
 			rawConfigs: {
 				entryWorker: entryWorkerResolvedConfig,
@@ -182,7 +178,6 @@ export function resolvePluginConfig(
 		type: "workers",
 		configPaths,
 		persistState,
-		inspectorPort,
 		workers,
 		entryWorkerEnvironmentName,
 		rawConfigs: {

packages/vite-plugin-cloudflare/src/utils.ts

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import getPort, { portNumbers } from "get-port";
 import { Request as MiniflareRequest } from "miniflare";
 import * as vite from "vite";
 import { ROUTER_WORKER_NAME } from "./constants";
@@ -66,3 +67,7 @@ export function cleanUrl(url: string): string {
 export type Optional<T, K extends keyof T> = Omit<T, K> & Pick<Partial<T>, K>;
 
 export type MaybePromise<T> = Promise<T> | T;
+
+export function getFirstAvailablePort(start: number) {
+	return getPort({ port: portNumbers(start, 65535) });
+}