From b6075b50b5789235a4d1217230cb269f3845170b Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Sat, 1 Aug 2026 10:17:55 +0200
Subject: [PATCH] module: add module.entrypoint

Add `module.entrypoint`, a property exposing the resolved URL of the
entry point of the current thread. Unlike `require.main`, it works
regardless of whether the entry point is a CommonJS or an ECMAScript
module, and inside worker threads it reflects the entry point of the
worker itself, matching the semantics of `require.main` and
`import.meta.main`.

Refs: https://github.com/nodejs/node/issues/51840
Refs: https://github.com/nodejs/node/pull/64800
Signed-off-by: Matteo Collina <hello@matteocollina.com>
---
 doc/api/module.md                             | 46 ++++++++++++
 lib/internal/main/worker_thread.js            |  1 +
 lib/internal/modules/helpers.js               | 14 ++++
 lib/internal/modules/run_main.js              |  5 ++
 lib/module.js                                 | 12 +++
 test/fixtures/module-entrypoint/main.cjs      |  8 ++
 test/fixtures/module-entrypoint/main.mjs      |  6 ++
 test/fixtures/module-entrypoint/noext.js      |  3 +
 .../module-entrypoint/worker-main.mjs         | 28 +++++++
 test/fixtures/module-entrypoint/worker.cjs    |  6 ++
 test/parallel/test-module-entrypoint.js       | 73 +++++++++++++++++++
 11 files changed, 202 insertions(+)
 create mode 100644 test/fixtures/module-entrypoint/main.cjs
 create mode 100644 test/fixtures/module-entrypoint/main.mjs
 create mode 100644 test/fixtures/module-entrypoint/noext.js
 create mode 100644 test/fixtures/module-entrypoint/worker-main.mjs
 create mode 100644 test/fixtures/module-entrypoint/worker.cjs
 create mode 100644 test/parallel/test-module-entrypoint.js

diff --git a/doc/api/module.md b/doc/api/module.md
index 956b10942ba3..7f4c98e23ed6 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -66,6 +66,49 @@ const require = createRequire(import.meta.url);
 const siblingModule = require('./sibling-module');
 ```
 
+### `module.entrypoint`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string|undefined}
+
+The resolved URL of the entry point of the current thread, or `undefined` when
+Node.js was started without an entry point script (`--eval`, the REPL, or code
+piped via STDIN). It works regardless of whether the entry point is a
+CommonJS or an ECMAScript module.
+
+Inside a [worker thread][], `module.entrypoint` is the URL of the script the
+worker was started with, matching the semantics of `require.main` and
+[`import.meta.main`][], rather than the entry point of the process. Workers
+created with `eval: true` have an `undefined` entrypoint.
+
+Unlike `process.argv[1]`, the value is fully resolved: extension searching is
+applied, and symlinks are followed unless [`--preserve-symlinks-main`][] is
+set. This makes it consistent with the `require.main.filename` of a CommonJS
+entry point and the `import.meta.url` of an ECMAScript module entry point.
+
+The value is `undefined` in code that runs before the entry point has been
+resolved, such as modules preloaded with `--require`.
+
+```mjs
+import { entrypoint } from 'node:module';
+
+if (import.meta.url === entrypoint) {
+  console.log('This module is the entry point of the current thread');
+}
+```
+
+```cjs
+const { entrypoint } = require('node:module');
+const { pathToFileURL } = require('node:url');
+
+if (pathToFileURL(__filename).href === entrypoint) {
+  console.log('This module is the entry point of the current thread');
+}
+```
+
 ### `module.findPackageJSON(specifier[, base])`
 
 <!-- YAML
@@ -2056,6 +2099,7 @@ returned object contains the following keys:
 [`"exports"`]: packages.md#exports
 [`--enable-source-maps`]: cli.md#--enable-source-maps
 [`--import`]: cli.md#--importmodule
+[`--preserve-symlinks-main`]: cli.md#--preserve-symlinks-main
 [`--require`]: cli.md#-r---require-module
 [`NODE_COMPILE_CACHE=dir`]: cli.md#node_compile_cachedir
 [`NODE_COMPILE_CACHE_PORTABLE=1`]: cli.md#node_compile_cache_portable1
@@ -2063,6 +2107,7 @@ returned object contains the following keys:
 [`NODE_V8_COVERAGE=dir`]: cli.md#node_v8_coveragedir
 [`Object.freeze()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze
 [`SourceMap`]: #class-modulesourcemap
+[`import.meta.main`]: esm.md#importmetamain
 [`initialize`]: #initialize
 [`module.constants.compileCacheStatus`]: #moduleconstantscompilecachestatus
 [`module.enableCompileCache()`]: #moduleenablecompilecacheoptions
@@ -2091,3 +2136,4 @@ returned object contains the following keys:
 [the documentation of `Worker`]: worker_threads.md#new-workerfilename-options
 [transferable objects]: worker_threads.md#portpostmessagevalue-transferlist
 [type-stripping]: typescript.md#type-stripping
+[worker thread]: worker_threads.md
diff --git a/lib/internal/main/worker_thread.js b/lib/internal/main/worker_thread.js
index 8a58dc0cba0f..ca65899b3a44 100644
--- a/lib/internal/main/worker_thread.js
+++ b/lib/internal/main/worker_thread.js
@@ -202,6 +202,7 @@ port.on('message', (message) => {
 
       case 'data-url': {
         const { runEntryPointWithESMLoader } = require('internal/modules/run_main');
+        require('internal/modules/helpers').setEntrypoint(filename);
 
         RegExpPrototypeExec(/^/, ''); // Necessary to reset RegExp statics before user code runs.
         const promise = runEntryPointWithESMLoader((cascadedLoader) => {
diff --git a/lib/internal/modules/helpers.js b/lib/internal/modules/helpers.js
index 62b8a743942b..b13b7c554f83 100644
--- a/lib/internal/modules/helpers.js
+++ b/lib/internal/modules/helpers.js
@@ -518,6 +518,14 @@ function getCompileCacheDir() {
   return _getCompileCacheDir() || undefined;
 }
 
+/**
+ * The resolved URL of the entry point of the current thread, if it was
+ * started with an entry point (i.e. not eval, REPL or STDIN input).
+ * In worker threads this is the entry point of the worker, not the process.
+ * @type {string|undefined}
+ */
+let entrypoint;
+
 function getRequireStack(parent) {
   const requireStack = [];
   for (let cursor = parent;
@@ -547,6 +555,12 @@ module.exports = {
   stringify,
   stripBOM,
   toRealPath,
+  getEntrypoint() {
+    return entrypoint;
+  },
+  setEntrypoint(url) {
+    entrypoint = url;
+  },
   hasStartedUserCJSExecution() {
     return _hasStartedUserCJSExecution;
   },
diff --git a/lib/internal/modules/run_main.js b/lib/internal/modules/run_main.js
index 2974459755ec..aa0e38829f08 100644
--- a/lib/internal/modules/run_main.js
+++ b/lib/internal/modules/run_main.js
@@ -146,15 +146,20 @@ function executeUserEntryPoint(main = process.argv[1]) {
     resolvedMain = resolveMainPath(main);
     useESMLoader = shouldUseESMLoader(resolvedMain);
   }
+  const { setEntrypoint } = require('internal/modules/helpers');
   // Unless we know we should use the ESM loader to handle the entry point per the checks in `shouldUseESMLoader`, first
   // try to run the entry point via the CommonJS loader; and if that fails under certain conditions, retry as ESM.
   if (!useESMLoader) {
+    if (resolvedMain !== undefined) {
+      setEntrypoint(pathToFileURL(resolvedMain).href);
+    }
     const cjsLoader = require('internal/modules/cjs/loader');
     const { wrapModuleLoad } = cjsLoader;
     wrapModuleLoad(main, null, true);
   } else {
     const mainPath = resolvedMain || main;
     const mainURL = getOptionValue('--entry-url') ? new URL(mainPath, getCWDURL()) : pathToFileURL(mainPath);
+    setEntrypoint(mainURL.href);
 
     runEntryPointWithESMLoader((cascadedLoader) => {
       // Note that if the graph contains unsettled TLA, this may never resolve
diff --git a/lib/module.js b/lib/module.js
index 1217172afb3c..71a4118cb092 100644
--- a/lib/module.js
+++ b/lib/module.js
@@ -1,5 +1,9 @@
 'use strict';
 
+const {
+  ObjectDefineProperty,
+} = primordials;
+
 const {
   findSourceMap,
   getSourceMapsSupport,
@@ -15,6 +19,7 @@ const {
   enableCompileCache,
   flushCompileCache,
   getCompileCacheDir,
+  getEntrypoint,
 } = require('internal/modules/helpers');
 const {
   findPackageJSON,
@@ -29,6 +34,13 @@ Module.flushCompileCache = flushCompileCache;
 Module.getCompileCacheDir = getCompileCacheDir;
 Module.stripTypeScriptTypes = stripTypeScriptTypes;
 
+ObjectDefineProperty(Module, 'entrypoint', {
+  __proto__: null,
+  configurable: true,
+  enumerable: true,
+  get: getEntrypoint,
+});
+
 // SourceMap APIs
 Module.findSourceMap = findSourceMap;
 Module.SourceMap = SourceMap;
diff --git a/test/fixtures/module-entrypoint/main.cjs b/test/fixtures/module-entrypoint/main.cjs
new file mode 100644
index 000000000000..63ffcc587202
--- /dev/null
+++ b/test/fixtures/module-entrypoint/main.cjs
@@ -0,0 +1,8 @@
+'use strict';
+
+const { entrypoint } = require('node:module');
+
+console.log(JSON.stringify({
+  entrypoint,
+  matchesMain: require('node:url').pathToFileURL(__filename).href === entrypoint,
+}));
diff --git a/test/fixtures/module-entrypoint/main.mjs b/test/fixtures/module-entrypoint/main.mjs
new file mode 100644
index 000000000000..b8ad75b5508d
--- /dev/null
+++ b/test/fixtures/module-entrypoint/main.mjs
@@ -0,0 +1,6 @@
+import { entrypoint } from 'node:module';
+
+console.log(JSON.stringify({
+  entrypoint,
+  matchesMain: import.meta.url === entrypoint,
+}));
diff --git a/test/fixtures/module-entrypoint/noext.js b/test/fixtures/module-entrypoint/noext.js
new file mode 100644
index 000000000000..6211c89143d9
--- /dev/null
+++ b/test/fixtures/module-entrypoint/noext.js
@@ -0,0 +1,3 @@
+'use strict';
+
+console.log(require('node:module').entrypoint);
diff --git a/test/fixtures/module-entrypoint/worker-main.mjs b/test/fixtures/module-entrypoint/worker-main.mjs
new file mode 100644
index 000000000000..770eece71980
--- /dev/null
+++ b/test/fixtures/module-entrypoint/worker-main.mjs
@@ -0,0 +1,28 @@
+import { entrypoint } from 'node:module';
+import { Worker } from 'node:worker_threads';
+import { once } from 'node:events';
+
+const fileWorker = new Worker(new URL('./worker.cjs', import.meta.url));
+const [fileWorkerEntrypoint] = await once(fileWorker, 'message');
+
+const evalWorker = new Worker(
+  'require("node:worker_threads").parentPort.postMessage(' +
+  'String(require("node:module").entrypoint));',
+  { eval: true },
+);
+const [evalWorkerEntrypoint] = await once(evalWorker, 'message');
+
+const dataURL = 'data:text/javascript,' + encodeURIComponent(
+  'import { entrypoint } from "node:module";' +
+  'import { parentPort } from "node:worker_threads";' +
+  'parentPort.postMessage(entrypoint);',
+);
+const dataURLWorker = new Worker(new URL(dataURL));
+const [dataURLWorkerEntrypoint] = await once(dataURLWorker, 'message');
+
+console.log(JSON.stringify({
+  entrypoint,
+  fileWorkerEntrypoint,
+  evalWorkerEntrypoint,
+  dataURLWorkerEntrypoint,
+}));
diff --git a/test/fixtures/module-entrypoint/worker.cjs b/test/fixtures/module-entrypoint/worker.cjs
new file mode 100644
index 000000000000..5cbcaaf39423
--- /dev/null
+++ b/test/fixtures/module-entrypoint/worker.cjs
@@ -0,0 +1,6 @@
+'use strict';
+
+const { entrypoint } = require('node:module');
+const { parentPort } = require('node:worker_threads');
+
+parentPort.postMessage(entrypoint);
diff --git a/test/parallel/test-module-entrypoint.js b/test/parallel/test-module-entrypoint.js
new file mode 100644
index 000000000000..a641d70d571d
--- /dev/null
+++ b/test/parallel/test-module-entrypoint.js
@@ -0,0 +1,73 @@
+'use strict';
+
+// Tests that `module.entrypoint` exposes the resolved URL of the entry point
+// of the current thread, matching the semantics of `require.main`.
+
+const { spawnPromisified } = require('../common');
+const fixtures = require('../common/fixtures');
+const assert = require('node:assert');
+const { spawnSync } = require('node:child_process');
+const { realpathSync } = require('node:fs');
+const { test } = require('node:test');
+const { pathToFileURL } = require('node:url');
+
+function fixtureURL(...args) {
+  // The entrypoint is fully resolved, so account for symlinks in the path
+  // to the fixtures directory.
+  return pathToFileURL(realpathSync(fixtures.path('module-entrypoint', ...args))).href;
+}
+
+test('CommonJS entry point', async () => {
+  const entry = fixtures.path('module-entrypoint', 'main.cjs');
+  const { code, stdout } = await spawnPromisified(process.execPath, [entry]);
+  assert.strictEqual(code, 0);
+  assert.deepStrictEqual(JSON.parse(stdout), {
+    entrypoint: fixtureURL('main.cjs'),
+    matchesMain: true,
+  });
+});
+
+test('ESM entry point', async () => {
+  const entry = fixtures.path('module-entrypoint', 'main.mjs');
+  const { code, stdout } = await spawnPromisified(process.execPath, [entry]);
+  assert.strictEqual(code, 0);
+  assert.deepStrictEqual(JSON.parse(stdout), {
+    entrypoint: fixtureURL('main.mjs'),
+    matchesMain: true,
+  });
+});
+
+test('extensionless entry point is resolved', async () => {
+  const entry = fixtures.path('module-entrypoint', 'noext');
+  const { code, stdout } = await spawnPromisified(process.execPath, [entry]);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(stdout.trim(), fixtureURL('noext.js'));
+});
+
+test('worker threads get their own entrypoint', async () => {
+  const entry = fixtures.path('module-entrypoint', 'worker-main.mjs');
+  const { code, stdout } = await spawnPromisified(process.execPath, [entry]);
+  assert.strictEqual(code, 0);
+  const result = JSON.parse(stdout);
+  assert.strictEqual(result.entrypoint, fixtureURL('worker-main.mjs'));
+  assert.strictEqual(result.fileWorkerEntrypoint, fixtureURL('worker.cjs'));
+  assert.strictEqual(result.evalWorkerEntrypoint, 'undefined');
+  assert.match(result.dataURLWorkerEntrypoint, /^data:text\/javascript,/);
+});
+
+test('undefined for --eval', async () => {
+  const { code, stdout } = await spawnPromisified(process.execPath, [
+    '--eval', 'console.log(String(require("node:module").entrypoint));',
+  ]);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(stdout.trim(), 'undefined');
+});
+
+test('undefined for STDIN input', () => {
+  const { status, stdout } = spawnSync(process.execPath, [], {
+    input: 'console.log(String(require("node:module").entrypoint));',
+    encoding: 'utf8',
+  });
+  assert.strictEqual(status, 0);
+  assert.strictEqual(stdout.trim(), 'undefined');
+});