From dc8e9f9921c94eda3a780ab76ab267c160afb4ad Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Sat, 1 Aug 2026 10:17:55 +0200
Subject: [PATCH 1/2] 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                             | 50 +++++++++++++
 lib/internal/main/worker_thread.js            |  1 +
 lib/internal/modules/helpers.js               | 14 ++++
 lib/internal/modules/run_main.js              |  6 +-
 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, 206 insertions(+), 1 deletion(-)
 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 f86167e8d44f..c10f3ef1086d 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -70,6 +70,53 @@ 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`.
+
+Unlike [`import.meta.main`][], which only returns a boolean, `module.entrypoint`
+returns the resolved URL string of the entry point. It can be used as a base
+for resolving paths relative to the entry point, regardless of whether the
+entry point is a CommonJS or an ECMAScript module:
+
+```mjs
+import { entrypoint } from 'node:module';
+
+// Use the entry point's URL as a base for resolving sibling modules.
+const base = new URL('./', entrypoint);
+```
+
+In CommonJS, the equivalent is:
+
+```cjs
+const { entrypoint } = require('node:module');
+
+// Use the entry point's URL as a base for resolving sibling modules.
+const base = new URL('./', entrypoint);
+```
+
 ## `module.findPackageJSON(specifier[, base])`
 
 <!-- YAML
@@ -2112,6 +2159,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
@@ -2120,6 +2168,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
@@ -2148,3 +2197,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 1f5fa8f8212b..fcba929022c1 100644
--- a/lib/internal/main/worker_thread.js
+++ b/lib/internal/main/worker_thread.js
@@ -227,6 +227,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 e30b892ad5eb..4e9ed89305aa 100644
--- a/lib/internal/modules/helpers.js
+++ b/lib/internal/modules/helpers.js
@@ -657,6 +657,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;
@@ -724,6 +732,12 @@ module.exports = {
   setLoaderOverrides,
   stringify,
   stripBOM,
+  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 b0d7d4845eaf..baeb151d7730 100644
--- a/lib/internal/modules/run_main.js
+++ b/lib/internal/modules/run_main.js
@@ -8,7 +8,7 @@ const {
 const { getOptionValue } = require('internal/options');
 // Through loaderMethods rather than the `modules` binding directly: a mounted
 // VFS overrides these, and a worker entry point can live inside one.
-const { loaderMethods } = require('internal/modules/helpers');
+const { loaderMethods, setEntrypoint } = require('internal/modules/helpers');
 const path = require('path');
 const { pathToFileURL, URL } = require('internal/url');
 const { kEmptyObject, getCWDURL } = require('internal/util');
@@ -168,12 +168,16 @@ function executeUserEntryPoint(main = process.argv[1]) {
   // 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);
 
     // When no async loader hooks or --import are registered, load the entry point
     // directly. The graph is loaded and linked synchronously, and evaluated
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');
+});

From 8de4ee3918284202bc7ff1062d6fd03215fc6b08 Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Wed, 5 Aug 2026 10:42:49 +0100
Subject: [PATCH 2/2] test: check stdout before exit code in module-entrypoint
 test

Address review feedback from aduh95.

Signed-off-by: Matteo Collina <hello@matteocollina.com>
---
 test/parallel/test-module-entrypoint.js | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/test/parallel/test-module-entrypoint.js b/test/parallel/test-module-entrypoint.js
index a641d70d571d..a61759126698 100644
--- a/test/parallel/test-module-entrypoint.js
+++ b/test/parallel/test-module-entrypoint.js
@@ -12,7 +12,10 @@ 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
+  // Unlike fixtures.fileURL(), this resolves symlinks in the path to the
+  // fixtures directory: module.entrypoint is always fully resolved (unless
+  // --preserve-symlinks-main is set), so the expected URL needs to be too,
+  // otherwise this test would be flaky on checkouts that symlink their way
   // to the fixtures directory.
   return pathToFileURL(realpathSync(fixtures.path('module-entrypoint', ...args))).href;
 }
@@ -20,47 +23,47 @@ function fixtureURL(...args) {
 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,
   });
+  assert.strictEqual(code, 0);
 });
 
 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,
   });
+  assert.strictEqual(code, 0);
 });
 
 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'));
+  assert.strictEqual(code, 0);
 });
 
 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,/);
+  assert.strictEqual(code, 0);
 });
 
 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');
+  assert.strictEqual(code, 0);
 });
 
 test('undefined for STDIN input', () => {
@@ -68,6 +71,6 @@ test('undefined for STDIN input', () => {
     input: 'console.log(String(require("node:module").entrypoint));',
     encoding: 'utf8',
   });
-  assert.strictEqual(status, 0);
   assert.strictEqual(stdout.trim(), 'undefined');
+  assert.strictEqual(status, 0);
 });