src: support import() and import.meta in embedder-run modules

joyeecheung · aduh95 · commit a3488cc7987d · 2026-04-05T02:10:38.000+02:00
This adds a embedder_module_hdo for identifying embedder-run modules in the dynamic import handler and import.meta initializer, and a SourceTextModuleTypes for customizing source text module compilation in the JS land via compileSourceTextModule(). Also, refactors the existing embedder module compilation code to reuse the builtin resolution logic. PR-URL: nodejs#61654 Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Aditi Singh <aditisingh1400@gmail.com>
diff --git a/lib/internal/main/embedding.js b/lib/internal/main/embedding.js
@@ -15,16 +15,12 @@ const {
 const { isExperimentalSeaWarningNeeded, isSea } = internalBinding('sea');
 const { emitExperimentalWarning } = require('internal/util');
 const { emitWarningSync } = require('internal/process/warning');
-const { BuiltinModule } = require('internal/bootstrap/realm');
-const { normalizeRequirableId } = BuiltinModule;
 const { Module } = require('internal/modules/cjs/loader');
 const { compileFunctionForCJSLoader } = internalBinding('contextify');
 const { maybeCacheSourceMap } = require('internal/source_map/source_map_cache');
-const { codes: {
-  ERR_UNKNOWN_BUILTIN_MODULE,
-} } = require('internal/errors');
 const { pathToFileURL } = require('internal/url');
-const { loadBuiltinModule } = require('internal/modules/helpers');
+const { loadBuiltinModuleForEmbedder } = require('internal/modules/helpers');
+const { compileSourceTextModuleForEmbedder } = require('internal/modules/esm/utils');
 const { moduleFormats } = internalBinding('modules');
 const assert = require('internal/assert');
 const path = require('path');
@@ -34,7 +30,6 @@ const path = require('path');
 prepareMainThreadExecution(false, true);
 
 const isLoadingSea = isSea();
-const isBuiltinWarningNeeded = isLoadingSea && isExperimentalSeaWarningNeeded();
 if (isExperimentalSeaWarningNeeded()) {
   emitExperimentalWarning('Single executable application');
 }
@@ -103,28 +98,8 @@ function embedderRunCjs(content, filename) {
   );
 }
 
-let warnedAboutBuiltins = false;
-function warnNonBuiltinInSEA() {
-  if (isBuiltinWarningNeeded && !warnedAboutBuiltins) {
-    emitWarningSync(
-      'Currently the require() provided to the main script embedded into ' +
-      'single-executable applications only supports loading built-in modules.\n' +
-      'To load a module from disk after the single executable application is ' +
-      'launched, use require("module").createRequire().\n' +
-      'Support for bundled module loading or virtual file systems are under ' +
-      'discussions in https://github.com/nodejs/single-executable');
-    warnedAboutBuiltins = true;
-  }
-}
-
 function embedderRequire(id) {
-  const normalizedId = normalizeRequirableId(id);
-
-  if (!normalizedId) {
-    warnNonBuiltinInSEA();
-    throw new ERR_UNKNOWN_BUILTIN_MODULE(id);
-  }
-  return require(normalizedId);
+  return loadBuiltinModuleForEmbedder(id).exports;
 }
 
 function embedderRunESM(content, filename) {
@@ -134,31 +109,10 @@ function embedderRunESM(content, filename) {
   } else {
     resourceName = filename;
   }
-  const { compileSourceTextModule } = require('internal/modules/esm/utils');
-  // TODO(joyeecheung): support code cache, dynamic import() and import.meta.
-  const wrap = compileSourceTextModule(resourceName, content);
-  // Cache the source map for the module if present.
-  if (wrap.sourceMapURL) {
-    maybeCacheSourceMap(resourceName, content, wrap, false, undefined, wrap.sourceMapURL);
-  }
-  const requests = wrap.getModuleRequests();
-  const modules = [];
-  for (let i = 0; i < requests.length; ++i) {
-    const { specifier } = requests[i];
-    const normalizedId = normalizeRequirableId(specifier);
-    if (!normalizedId) {
-      warnNonBuiltinInSEA();
-      throw new ERR_UNKNOWN_BUILTIN_MODULE(specifier);
-    }
-    const mod = loadBuiltinModule(normalizedId);
-    if (!mod) {
-      throw new ERR_UNKNOWN_BUILTIN_MODULE(specifier);
-    }
-    modules.push(mod.getESMFacade());
-  }
-  wrap.link(modules);
-  wrap.instantiate();
-  wrap.evaluate(-1, false);
+  // TODO(joyeecheung): allow configuration from node::ModuleData,
+  // either via a more generic context object, or something like import.meta extensions.
+  const context = { isMain: true, __proto__: null };
+  const wrap = compileSourceTextModuleForEmbedder(resourceName, content, context);
 
   // TODO(joyeecheung): we may want to return the v8::Module via a vm.SourceTextModule
   // when vm.SourceTextModule stablizes, or put it in an out parameter.
diff --git a/lib/internal/modules/esm/utils.js b/lib/internal/modules/esm/utils.js
@@ -14,6 +14,7 @@ const {
   },
 } = internalBinding('util');
 const {
+  embedder_module_hdo,
   source_text_module_default_hdo,
   vm_dynamic_import_default_internal,
   vm_dynamic_import_main_context_default,
@@ -43,6 +44,7 @@ const {
 const assert = require('internal/assert');
 const {
   normalizeReferrerURL,
+  loadBuiltinModuleForEmbedder,
 } = require('internal/modules/helpers');
 
 let defaultConditions;
@@ -200,7 +202,8 @@ function defaultInitializeImportMetaForModule(meta, wrap) {
  * @param {ModuleWrap} wrap - The ModuleWrap of the SourceTextModule where `import.meta` is referenced.
  */
 function initializeImportMetaObject(symbol, meta, wrap) {
-  if (symbol === source_text_module_default_hdo) {
+  if (symbol === source_text_module_default_hdo ||
+      symbol === embedder_module_hdo) {
     defaultInitializeImportMetaForModule(meta, wrap);
     return;
   }
@@ -266,6 +269,10 @@ async function importModuleDynamicallyCallback(referrerSymbol, specifier, phase,
   if (referrerSymbol === source_text_module_default_hdo) {
     return defaultImportModuleDynamicallyForModule(specifier, phase, attributes, referrerName);
   }
+  // For embedder entry point ESM, only allow built-in modules.
+  if (referrerSymbol === embedder_module_hdo) {
+    return loadBuiltinModuleForEmbedder(specifier).getESMFacade().getNamespace();
+  }
 
   if (moduleRegistries.has(referrerSymbol)) {
     const { importModuleDynamically, callbackReferrer } = moduleRegistries.get(referrerSymbol);
@@ -334,6 +341,37 @@ function compileSourceTextModule(url, source, cascadedLoader, context = kEmptyOb
 }
 
 
+/**
+ * Compile, link, instantiate and evaluate a SourceTextModule for embedder ESM entry point.
+ * This resolves only built-in modules and uses the embedder_module_hdo for import.meta
+ * and dynamic import() support.
+ * @param {string} url URL of the module.
+ * @param {string} source Source code of the module.
+ * @param {{ isMain?: boolean }|undefined} context - context object containing module metadata.
+ * @returns {ModuleWrap}
+ */
+function compileSourceTextModuleForEmbedder(url, source, context = kEmptyObject) {
+  const wrap = new ModuleWrap(url, undefined, source, 0, 0, embedder_module_hdo);
+
+  const { isMain } = context;
+  if (isMain) {
+    wrap.isMain = true;
+  }
+
+  // Cache the source map for the module if present.
+  if (wrap.sourceMapURL) {
+    maybeCacheSourceMap(url, source, wrap, false, wrap.sourceURL, wrap.sourceMapURL);
+  }
+
+  // For embedder ESM, handle linking and evaluation.
+  const requests = wrap.getModuleRequests();
+  const modules = requests.map(({ specifier }) => loadBuiltinModuleForEmbedder(specifier).getESMFacade());
+  wrap.link(modules);
+  wrap.instantiate();
+  wrap.evaluate(-1, false);
+  return wrap;
+}
+
 const kImportInImportedESM = Symbol('kImportInImportedESM');
 const kImportInRequiredESM = Symbol('kImportInRequiredESM');
 const kRequireInImportedCJS = Symbol('kRequireInImportedCJS');
@@ -344,11 +382,13 @@ const kRequireInImportedCJS = Symbol('kRequireInImportedCJS');
 const requestTypes = { kImportInImportedESM, kImportInRequiredESM, kRequireInImportedCJS };
 
 module.exports = {
+  embedder_module_hdo,
   registerModule,
   initializeESM,
   getDefaultConditions,
   getConditionsSet,
   shouldSpawnLoaderHookWorker,
   compileSourceTextModule,
+  compileSourceTextModuleForEmbedder,
   requestTypes,
 };
diff --git a/lib/internal/modules/helpers.js b/lib/internal/modules/helpers.js
@@ -15,6 +15,7 @@ const {
 const {
   ERR_INVALID_ARG_TYPE,
   ERR_INVALID_RETURN_PROPERTY_VALUE,
+  ERR_UNKNOWN_BUILTIN_MODULE,
 } = require('internal/errors').codes;
 const { BuiltinModule } = require('internal/bootstrap/realm');
 
@@ -126,6 +127,43 @@ function loadBuiltinModule(id) {
   return mod;
 }
 
+let isSEABuiltinWarningNeeded_;
+function isSEABuiltinWarningNeeded() {
+  if (isSEABuiltinWarningNeeded_ === undefined) {
+    const { isExperimentalSeaWarningNeeded, isSea } = internalBinding('sea');
+    isSEABuiltinWarningNeeded_ = isSea() && isExperimentalSeaWarningNeeded();
+  }
+  return isSEABuiltinWarningNeeded_;
+}
+
+let warnedAboutBuiltins = false;
+/**
+ * Load a built-in module for embedder/SEA modules.
+ * @param {string} id
+ * @returns {import('internal/bootstrap/realm.js').BuiltinModule}
+ */
+function loadBuiltinModuleForEmbedder(id) {
+  const normalized = BuiltinModule.normalizeRequirableId(id);
+  if (normalized) {
+    const mod = loadBuiltinModule(normalized);
+    if (mod) {
+      return mod;
+    }
+  }
+  if (isSEABuiltinWarningNeeded() && !warnedAboutBuiltins) {
+    const { emitWarningSync } = require('internal/process/warning');
+    emitWarningSync(
+      'Currently the require() provided to the main script embedded into ' +
+      'single-executable applications only supports loading built-in modules.\n' +
+      'To load a module from disk after the single executable application is ' +
+      'launched, use require("module").createRequire().\n' +
+      'Support for bundled module loading or virtual file systems are under ' +
+      'discussions in https://github.com/nodejs/single-executable');
+    warnedAboutBuiltins = true;
+  }
+  throw new ERR_UNKNOWN_BUILTIN_MODULE(id);
+}
+
 /** @type {Module} */
 let $Module = null;
 /**
@@ -470,6 +508,7 @@ module.exports = {
   getCompileCacheDir,
   initializeCjsConditions,
   loadBuiltinModule,
+  loadBuiltinModuleForEmbedder,
   makeRequireFunction,
   normalizeReferrerURL,
   stringify,
diff --git a/src/env_properties.h b/src/env_properties.h
@@ -57,6 +57,7 @@
   V(onpskexchange_symbol, "onpskexchange")                                     \
   V(resource_symbol, "resource_symbol")                                        \
   V(trigger_async_id_symbol, "trigger_async_id_symbol")                        \
+  V(embedder_module_hdo, "embedder_module_hdo")                                \
   V(source_text_module_default_hdo, "source_text_module_default_hdo")          \
   V(vm_context_no_contextify, "vm_context_no_contextify")                      \
   V(vm_dynamic_import_default_internal, "vm_dynamic_import_default_internal")  \
