vite-node 3.2.0-beta.1 → 3.2.0-beta.3

package/dist/chunk-hmr.cjs

@@ -14,6 +14,7 @@ function viteNodeHmrPlugin() {
 	return {
 		name: "vite-node:hmr",
 		config() {
+			// chokidar fsevents is unstable on macos when emitting "ready" event
 			if (process.platform === "darwin" && false);
 		},
 		configureServer(server) {
@@ -23,6 +24,8 @@ function viteNodeHmrPlugin() {
 				_send(payload);
 				emitter.emit("message", payload);
 			};
+			// eslint-disable-next-line ts/ban-ts-comment
+			// @ts-ignore Vite 6 compat
 			const environments = server.environments;
 			if (environments) environments.ssr.hot.send = function(payload) {
 				_send(payload);
@@ -55,6 +58,7 @@ function sendMessageBuffer(runner, emitter) {
 	maps.messageBuffer.length = 0;
 }
 async function reload(runner, files) {
+	// invalidate module cache but not node_modules
 	Array.from(runner.moduleCache.keys()).forEach((fsPath) => {
 		if (!fsPath.includes("node_modules")) runner.moduleCache.delete(fsPath);
 	});
@@ -82,9 +86,14 @@ async function fetchUpdate(runner, { path, acceptedPath }) {
 	acceptedPath = utils.normalizeRequestId(acceptedPath);
 	const maps = getCache(runner);
 	const mod = maps.hotModulesMap.get(path);
-	if (!mod) return;
+	if (!mod)
+ // In a code-splitting project,
+	// it is common that the hot-updating module is not loaded yet.
+	// https://github.com/vitejs/vite/issues/721
+	return;
 	const isSelfUpdate = path === acceptedPath;
 	let fetchedModule;
+	// determine the qualified callbacks before we re-import the modules
 	const qualifiedCallbacks = mod.callbacks.filter(({ deps }) => deps.includes(acceptedPath));
 	if (isSelfUpdate || qualifiedCallbacks.length > 0) {
 		const disposer = maps.disposeMap.get(acceptedPath);
@@ -115,6 +124,7 @@ async function handleMessage(runner, emitter, files, payload) {
 			await notifyListeners(runner, "vite:beforeUpdate", payload);
 			await Promise.all(payload.updates.map((update) => {
 				if (update.type === "js-update") return queueUpdate(runner, fetchUpdate(runner, update));
+				// css-update
 				console.error(`${browser.s.cyan("[vite-node]")} no support css hmr.}`);
 				return null;
 			}));
@@ -147,6 +157,8 @@ function createHotContext(runner, emitter, files, ownerPath) {
 	debugHmr("createHotContext", ownerPath);
 	const maps = getCache(runner);
 	if (!maps.dataMap.has(ownerPath)) maps.dataMap.set(ownerPath, {});
+	// when a file is hot updated, a new context is created
+	// clear its stale callbacks
 	const mod = maps.hotModulesMap.get(ownerPath);
 	if (mod) mod.callbacks = [];
 	const newListeners = new Map();
@@ -170,8 +182,12 @@ function createHotContext(runner, emitter, files, ownerPath) {
 			acceptDeps([ownerPath], callback && (([mod]) => callback(mod)));
 		},
 		accept(deps, callback) {
-			if (typeof deps === "function" || !deps) acceptDeps([ownerPath], ([mod]) => deps && deps(mod));
-			else if (typeof deps === "string") acceptDeps([deps], ([mod]) => callback && callback(mod));
+			if (typeof deps === "function" || !deps)
+ // self-accept: hot.accept(() => {})
+			acceptDeps([ownerPath], ([mod]) => deps && deps(mod));
+			else if (typeof deps === "string")
+ // explicit deps
+			acceptDeps([deps], ([mod]) => callback && callback(mod));
 			else if (Array.isArray(deps)) acceptDeps(deps, callback);
 			else throw new TypeError("invalid hot.accept() usage.");
 		},

package/dist/chunk-hmr.mjs

@@ -12,6 +12,7 @@ function viteNodeHmrPlugin() {
 	return {
 		name: "vite-node:hmr",
 		config() {
+			// chokidar fsevents is unstable on macos when emitting "ready" event
 			if (process.platform === "darwin" && false);
 		},
 		configureServer(server) {
@@ -21,6 +22,8 @@ function viteNodeHmrPlugin() {
 				_send(payload);
 				emitter.emit("message", payload);
 			};
+			// eslint-disable-next-line ts/ban-ts-comment
+			// @ts-ignore Vite 6 compat
 			const environments = server.environments;
 			if (environments) environments.ssr.hot.send = function(payload) {
 				_send(payload);
@@ -53,6 +56,7 @@ function sendMessageBuffer(runner, emitter) {
 	maps.messageBuffer.length = 0;
 }
 async function reload(runner, files) {
+	// invalidate module cache but not node_modules
 	Array.from(runner.moduleCache.keys()).forEach((fsPath) => {
 		if (!fsPath.includes("node_modules")) runner.moduleCache.delete(fsPath);
 	});
@@ -80,9 +84,14 @@ async function fetchUpdate(runner, { path, acceptedPath }) {
 	acceptedPath = normalizeRequestId(acceptedPath);
 	const maps = getCache(runner);
 	const mod = maps.hotModulesMap.get(path);
-	if (!mod) return;
+	if (!mod)
+ // In a code-splitting project,
+	// it is common that the hot-updating module is not loaded yet.
+	// https://github.com/vitejs/vite/issues/721
+	return;
 	const isSelfUpdate = path === acceptedPath;
 	let fetchedModule;
+	// determine the qualified callbacks before we re-import the modules
 	const qualifiedCallbacks = mod.callbacks.filter(({ deps }) => deps.includes(acceptedPath));
 	if (isSelfUpdate || qualifiedCallbacks.length > 0) {
 		const disposer = maps.disposeMap.get(acceptedPath);
@@ -113,6 +122,7 @@ async function handleMessage(runner, emitter, files, payload) {
 			await notifyListeners(runner, "vite:beforeUpdate", payload);
 			await Promise.all(payload.updates.map((update) => {
 				if (update.type === "js-update") return queueUpdate(runner, fetchUpdate(runner, update));
+				// css-update
 				console.error(`${s.cyan("[vite-node]")} no support css hmr.}`);
 				return null;
 			}));
@@ -145,6 +155,8 @@ function createHotContext(runner, emitter, files, ownerPath) {
 	debugHmr("createHotContext", ownerPath);
 	const maps = getCache(runner);
 	if (!maps.dataMap.has(ownerPath)) maps.dataMap.set(ownerPath, {});
+	// when a file is hot updated, a new context is created
+	// clear its stale callbacks
 	const mod = maps.hotModulesMap.get(ownerPath);
 	if (mod) mod.callbacks = [];
 	const newListeners = new Map();
@@ -168,8 +180,12 @@ function createHotContext(runner, emitter, files, ownerPath) {
 			acceptDeps([ownerPath], callback && (([mod]) => callback(mod)));
 		},
 		accept(deps, callback) {
-			if (typeof deps === "function" || !deps) acceptDeps([ownerPath], ([mod]) => deps && deps(mod));
-			else if (typeof deps === "string") acceptDeps([deps], ([mod]) => callback && callback(mod));
+			if (typeof deps === "function" || !deps)
+ // self-accept: hot.accept(() => {})
+			acceptDeps([ownerPath], ([mod]) => deps && deps(mod));
+			else if (typeof deps === "string")
+ // explicit deps
+			acceptDeps([deps], ([mod]) => callback && callback(mod));
 			else if (Array.isArray(deps)) acceptDeps(deps, callback);
 			else throw new TypeError("invalid hot.accept() usage.");
 		},

package/dist/cli.cjs

@@ -21,7 +21,7 @@ require('node:perf_hooks');
 require('es-module-lexer');
 require('./constants.cjs');
 
-var version = "3.2.0-beta.1";
+var version = "3.2.0-beta.3";
 
 const cli = cac("vite-node");
 cli.option("-r, --root <path>", "Use specified root directory").option("-c, --config <path>", "Use specified config file").option("-m, --mode <mode>", "Set env mode").option("-w, --watch", "Restart on file changes, similar to \"nodemon\"").option("--script", "Use vite-node as a script runner").option("--options <options>", "Use specified Vite server options").option("-v, --version", "Output the version number").option("-h, --help", "Display help for command");
@@ -76,7 +76,9 @@ async function run(files, options = {}) {
 		plugins: [options.watch && hmr.viteNodeHmrPlugin()]
 	});
 	if (Number(vite.version.split(".")[0]) < 6) await server$1.pluginContainer.buildStart({});
-	else await server$1.environments.client.pluginContainer.buildStart({});
+	else
+ // directly access client plugin container until https://github.com/vitejs/vite/issues/19607
+	await server$1.environments.client.pluginContainer.buildStart({});
 	const env = vite.loadEnv(server$1.config.mode, server$1.config.envDir, "");
 	for (const key in env) {
 		var _process$env;
@@ -97,6 +99,7 @@ async function run(files, options = {}) {
 			return hmr.createHotContext(runner, server$1.emitter, files, url);
 		}
 	});
+	// provide the vite define variable in this context
 	await runner.executeId("/@vite/env");
 	for (const file of files) await runner.executeFile(file);
 	if (!options.watch) await server$1.close();

package/dist/cli.mjs

@@ -3,23 +3,23 @@ import cac from 'cac';
 import { s } from './chunk-browser.mjs';
 import { createServer, version as version$1, loadEnv } from 'vite';
 import { ViteNodeRunner } from './client.mjs';
+import { v as viteNodeHmrPlugin, a as createHotContext, h as handleMessage } from './chunk-hmr.mjs';
 import { ViteNodeServer } from './server.mjs';
 import { installSourcemapsSupport } from './source-map.mjs';
 import { toArray } from './utils.mjs';
-import { v as viteNodeHmrPlugin, a as createHotContext, h as handleMessage } from './chunk-hmr.mjs';
 import 'node:module';
 import 'node:url';
 import 'node:vm';
 import 'debug';
 import 'pathe';
 import 'node:fs';
+import 'node:events';
 import 'node:assert';
 import 'node:perf_hooks';
 import 'es-module-lexer';
 import './constants.mjs';
-import 'node:events';
 
-var version = "3.2.0-beta.1";
+var version = "3.2.0-beta.3";
 
 const cli = cac("vite-node");
 cli.option("-r, --root <path>", "Use specified root directory").option("-c, --config <path>", "Use specified config file").option("-m, --mode <mode>", "Set env mode").option("-w, --watch", "Restart on file changes, similar to \"nodemon\"").option("--script", "Use vite-node as a script runner").option("--options <options>", "Use specified Vite server options").option("-v, --version", "Output the version number").option("-h, --help", "Display help for command");
@@ -74,7 +74,9 @@ async function run(files, options = {}) {
 		plugins: [options.watch && viteNodeHmrPlugin()]
 	});
 	if (Number(version$1.split(".")[0]) < 6) await server.pluginContainer.buildStart({});
-	else await server.environments.client.pluginContainer.buildStart({});
+	else
+ // directly access client plugin container until https://github.com/vitejs/vite/issues/19607
+	await server.environments.client.pluginContainer.buildStart({});
 	const env = loadEnv(server.config.mode, server.config.envDir, "");
 	for (const key in env) {
 		var _process$env;
@@ -95,6 +97,7 @@ async function run(files, options = {}) {
 			return createHotContext(runner, server.emitter, files, url);
 		}
 	});
+	// provide the vite define variable in this context
 	await runner.executeId("/@vite/env");
 	for (const file of files) await runner.executeFile(file);
 	if (!options.watch) await server.close();

package/dist/client.cjs

@@ -155,12 +155,14 @@ class ViteNodeRunner {
 		const { imports, importers } = mod;
 		if (importee) importers.add(importee);
 		const getStack = () => `stack:\n${[...callstack, fsPath].reverse().map((p) => `  - ${p}`).join("\n")}`;
+		// check circular dependency
 		if (callstack.includes(fsPath) || Array.from(imports.values()).some((i) => importers.has(i))) {
 			if (mod.exports) return mod.exports;
 		}
 		let debugTimer;
 		if (this.debug) debugTimer = setTimeout(() => console.warn(`[vite-node] module ${fsPath} takes over 2s to load.\n${getStack()}`), 2e3);
 		try {
+			// cached module
 			if (mod.promise) return await mod.promise;
 			const promise = this.directRequest(id, fsPath, callstack);
 			Object.assign(mod, {
@@ -183,6 +185,7 @@ class ViteNodeRunner {
 		const { path, exists } = utils.toFilePath(dep, this.root);
 		if (!this.options.resolveId || exists) return [dep, path];
 		const resolved = await this.options.resolveId(dep, importer);
+		// supported since Vite 5-beta.19
 		if (resolved === null || resolved === void 0 || (_resolved$meta = resolved.meta) === null || _resolved$meta === void 0 || (_resolved$meta = _resolved$meta["vite:alias"]) === null || _resolved$meta === void 0 ? void 0 : _resolved$meta.noResolved) {
 			const error = new Error(`Cannot find module '${id}'${importer ? ` imported from '${importer}'` : ""}.
 
@@ -206,6 +209,7 @@ class ViteNodeRunner {
 	}
 	async resolveUrl(id, importee) {
 		const resolveKey = `resolve:${id}`;
+		// put info about new import as soon as possible, so we can start tracking it
 		this.moduleCache.setByModuleId(resolveKey, { resolving: true });
 		try {
 			return await this._resolveUrl(id, importee);
@@ -221,6 +225,7 @@ class ViteNodeRunner {
 		try {
 			return await this.options.fetchModule(id);
 		} catch (cause) {
+			// rethrow vite error if it cannot load the module because it's not resolved
 			if (typeof cause === "object" && cause.code === "ERR_LOAD_URL" || typeof (cause === null || cause === void 0 ? void 0 : cause.message) === "string" && cause.message.includes("Failed to load url")) {
 				const error = new Error(`Cannot find ${utils.isBareImport(id) ? "package" : "module"} '${id}'${importer ? ` imported from '${importer}'` : ""}`, { cause });
 				error.code = "ERR_MODULE_NOT_FOUND";
@@ -253,6 +258,7 @@ class ViteNodeRunner {
 		if (transformed == null) throw new Error(`[vite-node] Failed to load "${id}" imported from ${callstack[callstack.length - 2]}`);
 		const { Object, Reflect, Symbol } = this.getContextPrimitives();
 		const modulePath = utils.cleanUrl(moduleId);
+		// disambiguate the `<UNIT>:/` on windows: see nodejs/node#31710
 		const href = node_url.pathToFileURL(modulePath).href;
 		const __filename = node_url.fileURLToPath(href);
 		const __dirname = path.dirname(__filename);
@@ -270,6 +276,8 @@ class ViteNodeRunner {
 		});
 		const SYMBOL_NOT_DEFINED = Symbol("not defined");
 		let moduleExports = SYMBOL_NOT_DEFINED;
+		// this proxy is triggered only on exports.{name} and module.exports access
+		// inside the module itself. imported module is always "exports"
 		const cjsExports = new Proxy(exports, {
 			get: (target, p, receiver) => {
 				if (Reflect.has(target, p)) return Reflect.get(target, p, receiver);
@@ -277,12 +285,16 @@ class ViteNodeRunner {
 			},
 			getPrototypeOf: () => Object.prototype,
 			set: (_, p, value) => {
+				// treat "module.exports =" the same as "exports.default =" to not have nested "default.default",
+				// so "exports.default" becomes the actual module
 				if (p === "default" && this.shouldInterop(modulePath, { default: value }) && cjsExports !== value) {
 					exportAll(cjsExports, value);
 					exports.default = value;
 					return true;
 				}
 				if (!Reflect.has(exports, "default")) exports.default = {};
+				// returns undefined, when accessing named exports, if default is not an object
+				// but is still present inside hasOwnKeys, this is Node behaviour for CJS
 				if (moduleExports !== SYMBOL_NOT_DEFINED && utils.isPrimitive(moduleExports)) {
 					defineExport(exports, p, () => void 0);
 					return true;
@@ -306,6 +318,7 @@ class ViteNodeRunner {
 				return cjsExports;
 			}
 		};
+		// Vite hot context
 		let hotContext;
 		if (this.options.createHotContext) Object.defineProperty(meta, "hot", {
 			enumerable: true,
@@ -318,11 +331,20 @@ class ViteNodeRunner {
 				hotContext = value;
 			}
 		});
+		// Be careful when changing this
+		// changing context will change amount of code added on line :114 (vm.runInThisContext)
+		// this messes up sourcemaps for coverage
+		// adjust `WRAPPER_LENGTH` variable in packages/coverage-v8/src/provider.ts if you do change this
 		const context = this.prepareContext({
 			__vite_ssr_import__: request,
 			__vite_ssr_dynamic_import__: request,
 			__vite_ssr_exports__: exports,
 			__vite_ssr_exportAll__: (obj) => exportAll(exports, obj),
+			__vite_ssr_exportName__: (name, getter) => Object.defineProperty(exports, name, {
+				enumerable: true,
+				configurable: true,
+				get: getter
+			}),
 			__vite_ssr_import_meta__: meta,
 			require: node_module.createRequire(href),
 			exports: cjsExports,
@@ -331,6 +353,7 @@ class ViteNodeRunner {
 			__dirname
 		});
 		debugExecute(__filename);
+		// remove shebang
 		if (transformed[0] === "#") transformed = transformed.replace(/^#!.*/, (s) => " ".repeat(s.length));
 		await this.runModule(context, transformed);
 		return exports;
@@ -344,6 +367,7 @@ class ViteNodeRunner {
 	}
 	async runModule(context, transformed) {
 		var _this$options$moduleE;
+		// add 'use strict' since ESM enables it by default
 		const codeDefinition = `'use strict';async (${Object.keys(context).join(",")})=>{{`;
 		const code = `${codeDefinition}${transformed}\n}}`;
 		const options = {
@@ -364,6 +388,8 @@ class ViteNodeRunner {
 	*/
 	shouldInterop(path, mod) {
 		if (this.options.interopDefault === false) return false;
+		// never interop ESM modules
+		// TODO: should also skip for `.js` with `type="module"`
 		return !path.endsWith(".mjs") && "default" in mod;
 	}
 	importExternalModule(path) {
@@ -415,6 +441,7 @@ function interopModule(mod) {
 		defaultExport
 	};
 }
+// keep consistency with Vite on how exports are defined
 function defineExport(exports, key, value) {
 	Object.defineProperty(exports, key, {
 		enumerable: true,
@@ -423,6 +450,8 @@ function defineExport(exports, key, value) {
 	});
 }
 function exportAll(exports, sourceModule) {
+	// #1120 when a module exports itself it causes
+	// call stack error
 	if (exports === sourceModule) return;
 	if (utils.isPrimitive(sourceModule) || Array.isArray(sourceModule) || sourceModule instanceof Promise) return;
 	for (const key in sourceModule) if (key !== "default" && !(key in exports)) try {

package/dist/client.mjs

@@ -153,12 +153,14 @@ class ViteNodeRunner {
 		const { imports, importers } = mod;
 		if (importee) importers.add(importee);
 		const getStack = () => `stack:\n${[...callstack, fsPath].reverse().map((p) => `  - ${p}`).join("\n")}`;
+		// check circular dependency
 		if (callstack.includes(fsPath) || Array.from(imports.values()).some((i) => importers.has(i))) {
 			if (mod.exports) return mod.exports;
 		}
 		let debugTimer;
 		if (this.debug) debugTimer = setTimeout(() => console.warn(`[vite-node] module ${fsPath} takes over 2s to load.\n${getStack()}`), 2e3);
 		try {
+			// cached module
 			if (mod.promise) return await mod.promise;
 			const promise = this.directRequest(id, fsPath, callstack);
 			Object.assign(mod, {
@@ -181,6 +183,7 @@ class ViteNodeRunner {
 		const { path, exists } = toFilePath(dep, this.root);
 		if (!this.options.resolveId || exists) return [dep, path];
 		const resolved = await this.options.resolveId(dep, importer);
+		// supported since Vite 5-beta.19
 		if (resolved === null || resolved === void 0 || (_resolved$meta = resolved.meta) === null || _resolved$meta === void 0 || (_resolved$meta = _resolved$meta["vite:alias"]) === null || _resolved$meta === void 0 ? void 0 : _resolved$meta.noResolved) {
 			const error = new Error(`Cannot find module '${id}'${importer ? ` imported from '${importer}'` : ""}.
 
@@ -204,6 +207,7 @@ class ViteNodeRunner {
 	}
 	async resolveUrl(id, importee) {
 		const resolveKey = `resolve:${id}`;
+		// put info about new import as soon as possible, so we can start tracking it
 		this.moduleCache.setByModuleId(resolveKey, { resolving: true });
 		try {
 			return await this._resolveUrl(id, importee);
@@ -219,6 +223,7 @@ class ViteNodeRunner {
 		try {
 			return await this.options.fetchModule(id);
 		} catch (cause) {
+			// rethrow vite error if it cannot load the module because it's not resolved
 			if (typeof cause === "object" && cause.code === "ERR_LOAD_URL" || typeof (cause === null || cause === void 0 ? void 0 : cause.message) === "string" && cause.message.includes("Failed to load url")) {
 				const error = new Error(`Cannot find ${isBareImport(id) ? "package" : "module"} '${id}'${importer ? ` imported from '${importer}'` : ""}`, { cause });
 				error.code = "ERR_MODULE_NOT_FOUND";
@@ -251,6 +256,7 @@ class ViteNodeRunner {
 		if (transformed == null) throw new Error(`[vite-node] Failed to load "${id}" imported from ${callstack[callstack.length - 2]}`);
 		const { Object, Reflect, Symbol } = this.getContextPrimitives();
 		const modulePath = cleanUrl(moduleId);
+		// disambiguate the `<UNIT>:/` on windows: see nodejs/node#31710
 		const href = pathToFileURL(modulePath).href;
 		const __filename = fileURLToPath(href);
 		const __dirname = dirname(__filename);
@@ -268,6 +274,8 @@ class ViteNodeRunner {
 		});
 		const SYMBOL_NOT_DEFINED = Symbol("not defined");
 		let moduleExports = SYMBOL_NOT_DEFINED;
+		// this proxy is triggered only on exports.{name} and module.exports access
+		// inside the module itself. imported module is always "exports"
 		const cjsExports = new Proxy(exports, {
 			get: (target, p, receiver) => {
 				if (Reflect.has(target, p)) return Reflect.get(target, p, receiver);
@@ -275,12 +283,16 @@ class ViteNodeRunner {
 			},
 			getPrototypeOf: () => Object.prototype,
 			set: (_, p, value) => {
+				// treat "module.exports =" the same as "exports.default =" to not have nested "default.default",
+				// so "exports.default" becomes the actual module
 				if (p === "default" && this.shouldInterop(modulePath, { default: value }) && cjsExports !== value) {
 					exportAll(cjsExports, value);
 					exports.default = value;
 					return true;
 				}
 				if (!Reflect.has(exports, "default")) exports.default = {};
+				// returns undefined, when accessing named exports, if default is not an object
+				// but is still present inside hasOwnKeys, this is Node behaviour for CJS
 				if (moduleExports !== SYMBOL_NOT_DEFINED && isPrimitive(moduleExports)) {
 					defineExport(exports, p, () => void 0);
 					return true;
@@ -304,6 +316,7 @@ class ViteNodeRunner {
 				return cjsExports;
 			}
 		};
+		// Vite hot context
 		let hotContext;
 		if (this.options.createHotContext) Object.defineProperty(meta, "hot", {
 			enumerable: true,
@@ -316,11 +329,20 @@ class ViteNodeRunner {
 				hotContext = value;
 			}
 		});
+		// Be careful when changing this
+		// changing context will change amount of code added on line :114 (vm.runInThisContext)
+		// this messes up sourcemaps for coverage
+		// adjust `WRAPPER_LENGTH` variable in packages/coverage-v8/src/provider.ts if you do change this
 		const context = this.prepareContext({
 			__vite_ssr_import__: request,
 			__vite_ssr_dynamic_import__: request,
 			__vite_ssr_exports__: exports,
 			__vite_ssr_exportAll__: (obj) => exportAll(exports, obj),
+			__vite_ssr_exportName__: (name, getter) => Object.defineProperty(exports, name, {
+				enumerable: true,
+				configurable: true,
+				get: getter
+			}),
 			__vite_ssr_import_meta__: meta,
 			require: createRequire(href),
 			exports: cjsExports,
@@ -329,6 +351,7 @@ class ViteNodeRunner {
 			__dirname
 		});
 		debugExecute(__filename);
+		// remove shebang
 		if (transformed[0] === "#") transformed = transformed.replace(/^#!.*/, (s) => " ".repeat(s.length));
 		await this.runModule(context, transformed);
 		return exports;
@@ -342,6 +365,7 @@ class ViteNodeRunner {
 	}
 	async runModule(context, transformed) {
 		var _this$options$moduleE;
+		// add 'use strict' since ESM enables it by default
 		const codeDefinition = `'use strict';async (${Object.keys(context).join(",")})=>{{`;
 		const code = `${codeDefinition}${transformed}\n}}`;
 		const options = {
@@ -362,6 +386,8 @@ class ViteNodeRunner {
 	*/
 	shouldInterop(path, mod) {
 		if (this.options.interopDefault === false) return false;
+		// never interop ESM modules
+		// TODO: should also skip for `.js` with `type="module"`
 		return !path.endsWith(".mjs") && "default" in mod;
 	}
 	importExternalModule(path) {
@@ -413,6 +439,7 @@ function interopModule(mod) {
 		defaultExport
 	};
 }
+// keep consistency with Vite on how exports are defined
 function defineExport(exports, key, value) {
 	Object.defineProperty(exports, key, {
 		enumerable: true,
@@ -421,6 +448,8 @@ function defineExport(exports, key, value) {
 	});
 }
 function exportAll(exports, sourceModule) {
+	// #1120 when a module exports itself it causes
+	// call stack error
 	if (exports === sourceModule) return;
 	if (isPrimitive(sourceModule) || Array.isArray(sourceModule) || sourceModule instanceof Promise) return;
 	for (const key in sourceModule) if (key !== "default" && !(key in exports)) try {

package/dist/hmr.d.ts

@@ -21,6 +21,8 @@ declare module "vite" {
 declare function createHmrEmitter(): HMREmitter;
 declare function viteNodeHmrPlugin(): Plugin;
 
+/* eslint-disable no-console */
+
 type ModuleNamespace = Record<string, any> & {
 	[Symbol.toStringTag]: "Module"
 };
@@ -30,6 +32,7 @@ interface HotModule {
 	callbacks: HotCallback[];
 }
 interface HotCallback {
+	// the dependencies must be fetchable paths
 	deps: string[];
 	fn: (modules: (ModuleNamespace | undefined)[]) => void;
 }

package/dist/server.cjs

@@ -34,6 +34,7 @@ function _interopNamespaceDefault(e) {
 
 var esModuleLexer__namespace = /*#__PURE__*/_interopNamespaceDefault(esModuleLexer);
 
+/* eslint-disable no-console */
 function hashCode(s) {
 	return s.split("").reduce((a, b) => {
 		a = (a << 5) - a + b.charCodeAt(0);
@@ -128,6 +129,7 @@ function guessCJSversion(id) {
 		]) if (fs.existsSync(i)) return i;
 	}
 }
+// The code from https://github.com/unjs/mlly/blob/c5bcca0cda175921344fd6de1bc0c499e73e5dac/src/syntax.ts#L51-L98
 async function isValidNodeImport(id) {
 	const extension = pathe.extname(id);
 	if (BUILTIN_EXTENSIONS.has(extension)) return true;
@@ -152,12 +154,17 @@ async function shouldExternalize(id, options, cache = _defaultExternalizeCache)
 }
 async function _shouldExternalize(id, options) {
 	if (utils.isNodeBuiltin(id)) return id;
+	// data: should be processed by native import,
+	// since it is a feature of ESM.
+	// also externalize network imports since nodejs allows it when --experimental-network-imports
 	if (id.startsWith("data:") || /^(?:https?:)?\/\//.test(id)) return id;
 	id = patchWindowsImportPath(id);
 	const moduleDirectories = (options === null || options === void 0 ? void 0 : options.moduleDirectories) || ["/node_modules/"];
 	if (matchExternalizePattern(id, moduleDirectories, options === null || options === void 0 ? void 0 : options.inline)) return false;
 	if ((options === null || options === void 0 ? void 0 : options.inlineFiles) && (options === null || options === void 0 ? void 0 : options.inlineFiles.includes(id))) return false;
 	if (matchExternalizePattern(id, moduleDirectories, options === null || options === void 0 ? void 0 : options.external)) return id;
+	// Unless the user explicitly opted to inline them, externalize Vite deps.
+	// They are too big to inline by default.
 	if ((options === null || options === void 0 ? void 0 : options.cacheDir) && id.includes(options.cacheDir)) return id;
 	const isLibraryModule = moduleDirectories.some((dir) => id.includes(dir));
 	const guessCJS = isLibraryModule && (options === null || options === void 0 ? void 0 : options.fallbackCJS);
@@ -204,13 +211,18 @@ class ViteNodeServer {
 	externalizeCache = new Map();
 	debugger;
 	constructor(server, options = {}) {
+		var _options$deps3;
 		this.server = server;
 		this.options = options;
-		var _options$deps3;
 		const ssrOptions = server.config.ssr;
 		options.deps ?? (options.deps = {});
 		options.deps.cacheDir = pathe.relative(server.config.root, options.deps.cacheDir || server.config.cacheDir);
 		if (ssrOptions) {
+			// we don't externalize ssr, because it has different semantics in Vite
+			// if (ssrOptions.external) {
+			//   options.deps.external ??= []
+			//   options.deps.external.push(...ssrOptions.external)
+			// }
 			if (ssrOptions.noExternal === true) {
 				var _options$deps;
 				(_options$deps = options.deps).inline ?? (_options$deps.inline = true);
@@ -240,6 +252,7 @@ class ViteNodeServer {
 			if (!dir.endsWith("/")) dir += "/";
 			return pathe.normalize(dir);
 		});
+		// always add node_modules as a module directory
 		if (!options.deps.moduleDirectories.includes("/node_modules/")) options.deps.moduleDirectories.push("/node_modules/");
 	}
 	shouldExternalize(id) {
@@ -293,6 +306,7 @@ class ViteNodeServer {
 		const moduleId = utils.normalizeModuleId(id);
 		this.assertMode(mode);
 		const promiseMap = this.fetchPromiseMap[mode];
+		// reuse transform for concurrent requests
 		if (!promiseMap.has(moduleId)) promiseMap.set(moduleId, this._fetchModule(moduleId, mode).finally(() => {
 			promiseMap.delete(moduleId);
 		}));
@@ -302,6 +316,7 @@ class ViteNodeServer {
 		const mode = transformMode || this.getTransformMode(id);
 		this.assertMode(mode);
 		const promiseMap = this.transformPromiseMap[mode];
+		// reuse transform for concurrent requests
 		if (!promiseMap.has(id)) promiseMap.set(id, this._transformRequest(id, filepath, mode).finally(() => {
 			promiseMap.delete(id);
 		}));
@@ -327,6 +342,7 @@ class ViteNodeServer {
 		if (module) return module;
 		const _modules = this.server.moduleGraph.getModulesByFile(file);
 		if (!_modules || !_modules.size) return null;
+		// find the latest changed module
 		const modules = [..._modules];
 		let mod = modules[0];
 		let latestMax = -1;
@@ -354,6 +370,9 @@ class ViteNodeServer {
 		const { path: filePath } = utils.toFilePath(id, this.server.config.root);
 		const moduleNode = this.getChangedModule(id, filePath);
 		const cache = this.fetchCaches[transformMode].get(filePath);
+		// lastUpdateTimestamp is the timestamp that marks the last time the module was changed
+		// if lastUpdateTimestamp is 0, then the module was not changed since the server started
+		// we test "timestamp === 0" for expressiveness, but it's not necessary
 		const timestamp = moduleNode ? Math.max(moduleNode.lastHMRTimestamp, moduleNode.lastInvalidationTimestamp) : 0;
 		if (cache && (timestamp === 0 || cache.timestamp >= timestamp)) return cache.result;
 		const time = Date.now();
@@ -401,6 +420,8 @@ class ViteNodeServer {
 			if (result) return result;
 		}
 		if (transformMode === "web") {
+			// for components like Vue, we want to use the client side
+			// plugins but then convert the code to be consumed by the server
 			result = await this.server.transformRequest(id);
 			if (result) result = await this.server.ssrTransform(result.code, result.map, id);
 		} else result = await this.server.transformRequest(id, { ssr: true });