feat(bundler): allow vite to auto increment port availability when in use

Author: NathanWalker

dependency-injection.md

@@ -324,6 +324,7 @@ contract and every existing caller sees it.
 | `ProjectNameService` | `projectNameService` |
 | `Prompter` | `prompter` |
 | `TempService` | `tempService` |
+| `ViteHmrPortService` | `viteHmrPortService` |
 
 And the injection tokens, for registrations that are not classes:
 

lib/bootstrap.ts

@@ -419,6 +419,10 @@ injector.require(
 	"bundlerCompilerService",
 	"./services/bundler/bundler-compiler-service",
 );
+injector.require(
+	"viteHmrPortService",
+	"./services/bundler/vite-hmr-port-service",
+);
 
 injector.require(
 	"applePortalSessionService",

lib/common/helpers.ts

@@ -362,6 +362,18 @@ export function toBoolean(str: any): boolean {
 	return !!(str && str.toString && str.toString().toLowerCase() === "true");
 }
 
+/**
+ * Reads an opt-in environment flag: any value other than empty / `0` /
+ * `false` / `off` / `no` turns it on.
+ */
+export function isTruthyEnvFlag(value: string | undefined): boolean {
+	if (typeof value !== "string") {
+		return false;
+	}
+	const v = value.trim().toLowerCase();
+	return !!v && v !== "0" && v !== "false" && v !== "off" && v !== "no";
+}
+
 export function block(operation: () => void): void {
 	if (isInteractive()) {
 		(<ReadStream>process.stdin).setRawMode(false);

lib/constants.ts

@@ -17,10 +17,11 @@ export const TNS_CORE_THEME_NAME = "nativescript-theme-core";
 export const SCOPED_TNS_CORE_THEME_NAME = "@nativescript/theme";
 export const WEBPACK_PLUGIN_NAME = "@nativescript/webpack";
 export const RSPACK_PLUGIN_NAME = "@nativescript/rspack";
-// Project-relative directory the Vite bundler writes its build output to
-// before the CLI copies it into the platforms app folder. Mirrors the
-// default value computed in `@nativescript/vite`'s base configuration
-// (`process.env.NS_VITE_DIST_DIR || '.ns-vite-build'`).
+// Root of the project-relative directory the Vite bundler writes its build
+// output to before the CLI copies it into the platforms app folder. The CLI
+// stages each platform in its own subdirectory (`.ns-vite-build/<platform>`)
+// and tells `@nativescript/vite` where via `NS_VITE_DIST_DIR`; the package's
+// own fallback (`.ns-vite-build`) only applies to standalone `vite` runs.
 export const VITE_DIST_FOLDER_NAME = ".ns-vite-build";
 export const TNS_CORE_MODULES_WIDGETS_NAME = "tns-core-modules-widgets";
 export const UI_MOBILE_BASE_NAME = "@nativescript/ui-mobile-base";

lib/contracts/index.ts

@@ -42,6 +42,7 @@ export { ProjectDataService } from "./project-data-service";
 export { ProjectNameService } from "./project-name-service";
 export { Prompter } from "./prompter";
 export { TempService } from "./temp-service";
+export { ViteHmrPortService } from "./vite-hmr-port-service";
 
 export { PBXPROJ_DOM_XCODE } from "./pbxproj-dom-xcode";
 export { XCODE } from "./xcode";

lib/contracts/vite-hmr-port-service.ts

@@ -0,0 +1,20 @@
+import { Contract } from "../common/di/contract";
+
+/**
+ * Chooses the local port the Vite HMR dev server binds for a platform.
+ */
+@Contract({ name: "viteHmrPortService" })
+export abstract class ViteHmrPortService {
+	/**
+	 * Resolves the port the Vite dev server for `platform` listens on: the
+	 * first free port at or above `NS_HMR_PORT` (default 5173) that no other
+	 * platform in this process holds. Resolved once per platform and stable
+	 * for the life of the process, so the build watcher (which bakes the port
+	 * into `bundle.mjs`), the dev server and the Android `adb reverse` tunnel
+	 * all agree on it.
+	 *
+	 * With `NS_HMR_STRICT_PORT` set, a busy preferred port fails instead of
+	 * moving to the next one.
+	 */
+	abstract getPort(platform: string): Promise<number>;
+}

lib/controllers/run-controller.ts

@@ -7,6 +7,7 @@ import {
 	USER_INTERACTION_NEEDED_EVENT_NAME,
 } from "../constants";
 import { cache, performanceLog } from "../common/decorators";
+import { isTruthyEnvFlag } from "../common/helpers";
 import { EventEmitter } from "events";
 import * as util from "util";
 import * as _ from "lodash";
@@ -22,6 +23,7 @@ import {
 	IDictionary,
 } from "../common/declarations";
 import { IInjector } from "../common/definitions/yok";
+import { ViteHmrPortService } from "../contracts/vite-hmr-port-service";
 import { injector } from "../common/yok";
 
 export class RunController extends EventEmitter implements IRunController {
@@ -58,6 +60,7 @@ export class RunController extends EventEmitter implements IRunController {
 		private $projectChangesService: IProjectChangesService,
 		protected $projectDataService: IProjectDataService,
 		private $staticConfig: Config.IStaticConfig,
+		private $viteHmrPortService: ViteHmrPortService,
 	) {
 		super();
 	}
@@ -692,18 +695,20 @@ export class RunController extends EventEmitter implements IRunController {
 			// Respect the user's explicit opt-out — they want the
 			// `10.0.2.2` / LAN path, so don't create a tunnel or claim one
 			// exists.
-			if (this.isTruthyEnvFlag(process.env.NS_HMR_NO_ADB_REVERSE)) {
+			if (isTruthyEnvFlag(process.env.NS_HMR_NO_ADB_REVERSE)) {
 				return;
 			}
 			// `NS_HMR_PREFER_LAN_HOST` means the dev wants LAN routing
 			// (physical device over Wi-Fi); the dev-host resolver suppresses
 			// the adb-reverse path for it, so don't bother wiring one.
-			if (this.isTruthyEnvFlag(process.env.NS_HMR_PREFER_LAN_HOST)) {
+			if (isTruthyEnvFlag(process.env.NS_HMR_PREFER_LAN_HOST)) {
 				return;
 			}
 
 			const serial = device.deviceInfo.identifier;
-			const port = this.getViteHmrPort();
+			const port = await this.$viteHmrPortService.getPort(
+				device.deviceInfo.platform,
+			);
 
 			if (phase === "pre-build") {
 				// Decide the origin baked into bundle.mjs. Hand the bundler our
@@ -733,7 +738,7 @@ export class RunController extends EventEmitter implements IRunController {
 			// + install (fresh emulators reconnect as they settle), silently
 			// dropping the early mapping. We only bother when we actually told
 			// the bundle to use `127.0.0.1` (READY set during pre-build).
-			if (!this.isTruthyEnvFlag(process.env.NS_ADB_REVERSE_READY)) {
+			if (!isTruthyEnvFlag(process.env.NS_ADB_REVERSE_READY)) {
 				return;
 			}
 			const ok = await this.ensureAndroidReverse(device, serial, port);
@@ -794,22 +799,6 @@ export class RunController extends EventEmitter implements IRunController {
 		return false;
 	}
 
-	private getViteHmrPort(): number {
-		// The Vite dev server defaults to 5173; the bundler reads the same
-		// default. If a project runs Vite on a different port, the dev sets
-		// `NS_HMR_PORT` so the CLI reverses the matching port.
-		const fromEnv = Number(process.env.NS_HMR_PORT);
-		return Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : 5173;
-	}
-
-	private isTruthyEnvFlag(value: string | undefined): boolean {
-		if (typeof value !== "string") {
-			return false;
-		}
-		const v = value.trim().toLowerCase();
-		return !!v && v !== "0" && v !== "false" && v !== "off" && v !== "no";
-	}
-
 	private async syncChangedDataOnDevices(
 		data: IFilesChangeEventData,
 		projectData: IProjectData,

lib/services/bundler/bundler-compiler-service.ts

@@ -33,6 +33,7 @@ import {
 	IHostInfo,
 } from "../../common/declarations";
 import { ICleanupService } from "../../definitions/cleanup-service";
+import { ViteHmrPortService } from "../../contracts/vite-hmr-port-service";
 import { injector } from "../../common/yok";
 import {
 	resolvePackagePath,
@@ -79,23 +80,37 @@ export class BundlerCompilerService
 		private $packageManager: IPackageManager,
 		private $packageInstallationManager: IPackageInstallationManager, // private $sharedEventBus: ISharedEventBus
 		private $projectConfigService: IProjectConfigService,
+		private $viteHmrPortService: ViteHmrPortService,
 	) {
 		super();
 	}
 
-	private getViteDistOutputPath(projectDir: string): string {
-		return path.join(
-			projectDir,
-			process.env.NS_VITE_DIST_DIR || VITE_DIST_FOLDER_NAME,
+	/**
+	 * Project-relative directory Vite stages its output in before the CLI
+	 * copies it into the platform app. Each platform gets its own directory
+	 * so concurrent iOS and Android sessions (separate terminals or one
+	 * `ns run`) never overwrite each other's bundle or vendor manifest.
+	 * `NS_VITE_DIST_DIR` overrides it verbatim.
+	 */
+	private getViteDistRelativeDir(platform: string): string {
+		return (
+			process.env.NS_VITE_DIST_DIR || `${VITE_DIST_FOLDER_NAME}/${platform}`
 		);
 	}
 
+	private getViteDistOutputPath(projectDir: string, platform: string): string {
+		return path.join(projectDir, this.getViteDistRelativeDir(platform));
+	}
+
 	private getViteBuildPaths(
 		platformData: IPlatformData,
 		projectData: IProjectData,
 	) {
 		return {
-			distOutput: this.getViteDistOutputPath(projectData.projectDir),
+			distOutput: this.getViteDistOutputPath(
+				projectData.projectDir,
+				platformData.platformNameLowerCase,
+			),
 			destDir: path.join(
 				platformData.appDestinationDirectoryPath,
 				this.$options.hostProjectModuleName,
@@ -566,6 +581,12 @@ export class BundlerCompilerService
 			...process.env,
 			NATIVESCRIPT_WEBPACK_ENV: JSON.stringify(envData),
 			NATIVESCRIPT_BUNDLER_ENV: JSON.stringify(envData),
+			...(isVite
+				? await this.getViteChildEnv(
+						platformData.platformNameLowerCase,
+						prepareData,
+					)
+				: {}),
 		};
 		if (this.$hostInfo.isWindows) {
 			Object.assign(options.env, { APPDATA: process.env.appData });
@@ -595,16 +616,46 @@ export class BundlerCompilerService
 		return childProcess;
 	}
 
-	private getViteHmrPort(): number {
-		const fromEnv = Number(process.env.NS_HMR_PORT);
-		return Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : 5173;
+	/**
+	 * Whether this prepare runs the long-lived Vite HMR dev server (vite +
+	 * HMR + watch, not release).
+	 */
+	private isViteHmrSession(prepareData: IPrepareData): boolean {
+		return (
+			this.getBundler() === "vite" &&
+			!!prepareData.watch &&
+			!!prepareData.hmr &&
+			!prepareData.release
+		);
+	}
+
+	/**
+	 * Environment both Vite children (the build watcher and the dev server)
+	 * must share for a platform: the staging directory, and — for HMR
+	 * sessions — the dev-server port. The port is resolved here, once, and
+	 * handed to `@nativescript/vite` as `NS_HMR_PORT`, so the URLs baked into
+	 * `bundle.mjs`, the server's bind and the `adb reverse` tunnel all match.
+	 */
+	private async getViteChildEnv(
+		platform: string,
+		prepareData: IPrepareData,
+	): Promise<IStringDictionary> {
+		const env: IStringDictionary = {
+			NS_VITE_DIST_DIR: this.getViteDistRelativeDir(platform),
+		};
+		if (this.isViteHmrSession(prepareData)) {
+			env.NS_HMR_PORT = String(
+				await this.$viteHmrPortService.getPort(platform),
+			);
+		}
+		return env;
 	}
 
 	/**
 	 * Spawn and manage the Vite dev server (`vite serve`) for HMR.
 	 *
 	 * Why the CLI owns this. With Vite, HMR needs a long-lived dev server
-	 * (HTTP + the `/ns-hmr` websocket on port 5173) that the device fetches
+	 * (HTTP + the `/ns-hmr` websocket) that the device fetches
 	 * modules and hot updates from — it is SEPARATE from the
 	 * `vite build --watch` process that emits the `bundle.mjs` bootstrap
 	 * baked into the app. Historically users wired this up themselves with
@@ -626,29 +677,16 @@ export class BundlerCompilerService
 		prepareData: IPrepareData,
 	): Promise<void> {
 		try {
-			if (this.getBundler() !== "vite") {
-				return;
-			}
-			if (!prepareData.watch || !prepareData.hmr || prepareData.release) {
+			if (!this.isViteHmrSession(prepareData)) {
 				return;
 			}
 			const key = platformData.platformNameLowerCase;
 			if (this.viteServeProcesses[key]) {
 				return;
 			}
 
-			const port = this.getViteHmrPort();
-			// One dev server per port. Simultaneous multi-platform HMR in a
-			// single CLI invocation would collide on 5173 — that case still
-			// needs a distinct NS_HMR_PORT per platform, so skip + warn rather
-			// than fail to bind.
-			const collidingPlatform = Object.keys(this.viteServeProcesses)[0];
-			if (collidingPlatform) {
-				this.$logger.warn(
-					`Vite dev server already running for '${collidingPlatform}' on port ${port}; skipping a second server for '${key}'. For simultaneous multi-platform HMR, set a distinct NS_HMR_PORT per platform.`,
-				);
-				return;
-			}
+			const viteEnv = await this.getViteChildEnv(key, prepareData);
+			const port = Number(viteEnv.NS_HMR_PORT);
 
 			const envData = this.buildEnvData(
 				platformData.platformNameLowerCase,
@@ -690,6 +728,7 @@ export class BundlerCompilerService
 				env: {
 					...process.env,
 					NATIVESCRIPT_BUNDLER_ENV: JSON.stringify(envData),
+					...viteEnv,
 				},
 			};
 			if (this.$hostInfo.isWindows) {