esm: implement import.meta.main #32223

aduh95 · 2020-03-12T11:27:39Z

Boolean value to check if a module is run as entry point of the current
process.

ES module authors need a way to determine if their code is run as CLI or as a dependency. #49440 have some proposal, I am implementing import.meta.main because:

it is arguably similar to the CJS pattern:

- if (module === require.main) {
+ if (import.meta.main) {

Deno has already implemented it, if we don't differ that is certainly easier for users to write code that runs everywhere.
It was suggested originally in the import.meta proposal.

Fixes: #49440

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

doc/api/esm.md

jasnell · 2020-03-12T15:39:39Z

What would the value be in a Worker thread?

aduh95 · 2020-03-12T18:39:59Z

What would the value be in a Worker thread?

Good question! With the current implementation, it is true for the Worker entry point, and false for sub-modules. To check if the current script is run as CLI, that means you also have to check for isMainThread value... I'm not sure if that's the behaviour we want to implement, but it definitely needs documentation of this topic.

devsnek

I'm against this for reasons outlined in the issue

jkrems

I might be convinced otherwise if there's overwhelming support for this feature but I have some concerns about this pattern (see issue comments). My concerns are broadly:

Usually import.meta doesn't change based on how and when the module has been imported. It's already "magic ephemeral data", let's not make it more dynamic and magic.
This pattern encourages writing code that's inherently untestable without setting up a custom module loader from scratch.
(More optional preference) I would vastly prefer a solution that properly encloses optional code that is meant to run as main and doesn't also allow sprinkling that behavior into random expressions. One example I suggested was to export a main or startup function for this purpose.

aduh95 · 2020-03-13T09:38:38Z

@jkrems regarding your first point, having a way to tell if current module is the entry point is a motivation clearly stated in the import.meta proposal. The way I understand it, it is supposed to be dynamic and magic.

I think your second point meets @devsnek's: using import.meta.main to run different code is not a good pattern. While I agree with this, I still firmly believe import.meta.main is a needed feature. My issue is currently when writing an ES module meant to be a CLI tool, there is no way to inform the user that they may have imported the wrong file:

import { isMainThread } from 'worker_threads';

if (!isMainThread || !import.meta.main) {
  process.emitWarning(new Error('This module should be run from CLI.'));
}

Regarding your third point, while it'd fine with me, I fail to see how exporting a main function is less magical than checking a boolean value.

devsnek · 2020-03-13T09:43:20Z

i think package exports can disallow importing your cli entrypoint. I also believe that "you've imported the wrong file" isn't specific to cli entrypoints, there are lots of files that libraries have that shouldn't be directly imported, which is why we should seek more general solutions.

Boolean value to check if a module is run as entry point of the current process. Fixes: https://gtihub.com/nodejs/modules/issues/274

addaleax

I’m good with this, personally.

aduh95 · 2020-08-27T14:22:07Z

Do we want to reconsider this? Asking because it's been recently brought up in #34882, it seems there are users looking for it.

guybedford · 2020-10-05T11:35:16Z

The use of import.meta.main is now highly established in the Deno ecosystem so I think it would be very benefical to move forward with this.

The other benefit of import.meta.main is it has a graceful failure when not supported, unlike most other import.meta features.

I think treating any new context as supporting import.meta.main makes sense as well so am happy with the worker support in this PR.

One pattern I also really like with import.meta.main is using it for creating in-module unit tests:

export function lib () {
  // ...implementation..
}

if (import.meta.main) {
  assert.strictEqual(lib('unit'), 'test');
}

where the tests are run by just running node src/lib.js for each internal module individually.

During a build, import.meta.main can then be optimized out as it can be completely statically inferred for the build without any extra metadata.

@jkrems perhaps that counters your untestable argument in (2) :) I do like the idea of having an exports condition, but that seems complementary to this proposal. Would seeing progress on that help overcome your and @devsnek's concerns here?

jkrems · 2020-10-05T16:14:46Z

During a build, import.meta.main can then be optimized out as it can be completely statically inferred for the build without any extra metadata.

What I think is very unfortunate about those kinds of tests, is that they'll never run in a browser without building. So it's effectively creating a test pattern that is browser-incompatible. Not something that node has to care about but I would prefer if we wouldn't encourage the creation of node-only (or bundler-only) code.

perhaps that counters your untestable argument in (2)

It's still "untestable" with the exception of exactly this case: The code inside of the block is a test itself, will only ever run as a subprocess, and doesn't require any testing/assertion framework (block-scoped import is way less convenient than block-scoped require). It doesn't allow running multiple tests inside of the same process (or loading them through a test runner bootstrap).

The use of import.meta.main is now highly established in the Deno ecosystem so I think it would be very benefical to move forward with this.

Afaik deno is still much smaller as an ecosystem than nodejs (let alone the browser). So adding a module system feature to nodejs because deno is doing it when the feature cannot be used in browsers (likely in perpetuity), isn't really convincing to me.

All that being said: These are all ecosystem concerns, not nodejs concerns. I'd be willing to dismiss my block to this change if there's a way to import a module as main without spawning a subprocess. That would make it somewhat testable at least and enable simple wrapper binaries.

aduh95 · 2020-10-05T18:24:04Z

The code inside of the block is a test itself, will only ever run as a subprocess[…]. It doesn't allow running multiple tests inside of the same process (or loading them through a test runner bootstrap).

Technically, it could be run on the same process using Workers.

adding a module system feature to nodejs because deno is doing it when the feature cannot be used in browsers (likely in perpetuity), isn't really convincing to me.

I suppose the web could also implement import.meta.main which would be true iif the module is run as web worker entry point. I reckon that's very speculative though, but if the feature gets traction from the community, I don't see why it couldn't happen.

If I'm being honest, the same argument applies to export function main pattern. Since there is no consensus amoung us, I was thinking maybe we could implement both behind a flag, then wait and see which gets the more popular. What do y'all think?

jkrems · 2020-10-05T18:31:10Z

If I'm being honest, the same argument applies to export function main pattern.

I don't think that's true. It's fairly simple to run a file using export main in the browser:

import {main} from './entrypoint.js';
main();

There's no need to parse & transform entrypoint.js, it works exactly as-is. With import.meta.main, entrypoint.js has to be parsed and transformed. It cannot be served directly with the contents the user wrote.

aduh95 · 2020-10-05T18:48:38Z

I don't think that's true. It's fairly simple to run a file using export main in the browser:

Yes sorry, I meant the fact that the HTML standard might implement import.meta.main is also true for export function main and is not a good argument for either at this point.

I think you're making a valid point with the browser compatibility thing, and I don't have any argument to counter that 😅

jkrems · 2020-10-05T19:20:35Z

Ah yes, sorry. Misread your comment about native browser support. :)

ExE-Boss · 2020-10-05T22:08:13Z

@jkrems
import.meta.main will simply be undefined in the browser.

The build step is about removing if (import.meta.main) { … } if statements in bundled modules that are not the entry module, because import.meta is shared in the context of the bundle:

Example:

Input:

// src/foo.js
if (import.meta.main) {
	throw new Error(`${import.meta.url} is not an entrypoint module`);
}

export function foo() { /* ... */ }

// src/main.js
import { foo } from "./foo.js";
export * from "./foo.js";

if (import.meta.main) {
	console.log(foo());
}

Output:

// dist/bundle.js
// src/foo.js
function foo() { /* ... */ }

// src/main.js
if (import.meta.main) {
	console.log(foo());
}

export { foo };

jkrems · 2020-10-05T22:13:32Z

import.meta.main will simply be undefined in the browser.

The build step is about removing if (import.meta.main) { … } if statements in bundled modules that are not the entry module, because import.meta is shared in the context of the bundle:

Yes, that's the problem. In the example above (where the thing inside of import.meta.main is a test), it's easy not to run the test but if I do want to run the test in a browser, only bundling could make the test actually run. In other words: The code in that block is 100% browser in-compatible. There's no API in the browser that could make the test usable if it's wrapped in import.meta.main.

guybedford · 2020-10-06T07:21:56Z

@jkrems it will likely be down to something like VM / compartments / realms to allow defining import.meta property hooks. Alternatively we could have a loader hook for this. The problem is on the one hand we are saying we can't add import.meta properties unless they can be customized, yet with the other we are stopping customization because we are saying they should be specified, but there is no way to specify anything for import.meta as the standard falls in the gap between standards bodies! So there we go.

jkrems · 2020-10-06T14:59:14Z

it will likely be down to something like VM / compartments / realms to allow defining import.meta property hooks.

I think that really doesn't address the usability concerns, just like loader hooks in node wouldn't. E.g. let's say somebody wrote two worker entrypoints, both using import.meta.main to guard the main logic. Now I want to run both in the same worker. Afaict with import.meta.main I just cannot. Even if there would be a loader hook, I would now have to write a custom loader hook just to compose two functions (effectively).

I get that the current UX (require.main) isn't great either - but at least it's relatively simple to load a CJS module as main (not that it's a great idea to do it repeatedly), the API is available on Module. But import.meta.main doesn't have any API to do it and the only API suggested so far (loader hook) would require starting the entire process with different flags and inspecting every single module load to match the one or two targeted modules.

Maybe there could be an API like Module.importAsMain(url)? Still doesn't work in browsers but at least allows composition in node without jumping through too many hoops.

rektide · 2021-02-25T04:02:22Z

please ship this. it's a huge help for a problem countless people run into regularly. allegedly it has risks and/or may not be 100% perfect for every use case (frankly i don't understand most of the concerns) but this seems straightforward & super helpful in 99.99% cases. not shipping it is really hurting us all very much. if we need a more foibled fancy alternative, let it emerge over time on some other import.meta. give us this straightforward common sense help which we very much need now.

guybedford · 2021-03-08T17:08:09Z

Perhaps we aren't clear on the meaning of import.meta.main? My assumption personally is it's more of a import.meta.cli_invocation_this_is_the__main_process_module flag, where setting it virtually would be customizable through generic hooks. I wouldn't expect it to apply to workers or any other VM entry points without such configurations provided explicitly. I haven't tested this cases in Deno though so can't say.

devsnek · 2021-03-08T17:09:24Z

@guybedford i'm still fundamentally opposed to this feature. even among people who want it, there is disagreement about what qualifies as "main".

With TLA you could do if (await import.meta.resolve(process.argv[1]) === import.meta.url) which is quite unambiguous.

atg · 2021-09-08T09:43:30Z

i'm still fundamentally opposed to this feature. even among people who want it, there is disagreement about what qualifies as "main".

If act of precisely specifying this feature has identified situations where the value of require.main is wrong, then sure go ahead and fix it in import.meta.main, but it seems that the exact semantics of require.main have not been a major pain point in the last 10 years, for most people require.main works just fine and they aren't running into these corner cases. So just decide on some semantics that are acceptable and ship it (please).

jkrems · 2021-09-08T15:43:59Z

it seems that the exact semantics of require.main have not been a major pain point in the last 10 years, for most people require.main works just fine and they aren't running into these corner cases.

One of the semantics of require.main is that it can be true for files imported in userland by using APIs exposed by node. If that wouldn't be true, people absolutely would run into corner cases, e.g. babel-node file.js would be hard or even impossible to implement somewhat efficiently (similar for other tools that want to be entry point wrappers). So it's true but the exact semantics of require.main have worked out okay. This implementation of import.meta.main doesn't replicate them though.

aduh95 · 2021-09-08T16:01:02Z

This implementation of import.meta.main doesn't replicate them though.

Why though? If someone is writing a custom loader, it doesn't seem very complicated to replace import.meta.main with true or false in the source code.

jkrems · 2021-09-08T18:18:29Z

Why though? If someone is writing a custom loader, it doesn't seem very complicated to replace import.meta.main with true or false in the source code.

I've written custom entry point wrappers in the past that didn't involve any source transformation. Setting the bar at "needs to do contextual compilation of all source code" seems excessive, compared to the status quo. It also makes it impossible to use node-profiling-wrapper main.js without worrying about interactions with "real" loaders that may be present.

It's fine if everybody agrees that this is an acceptable regression in the name of replicating the same API "look". But I think it's a meaningful difference that makes this not "just like" require.main. Again, fine to accept this difference. But I don't think it's valuable to just pretend like it doesn't exist.

avivkeller · 2024-07-17T18:37:26Z

Hey, this issue has been inactive for a bit, and recent issues have surfaced that reference this feature, is this still planned on being added / blocked?

CC @timfish #53882

guybedford · 2024-07-17T18:38:18Z

This sounds distinct from what is being discussed in #53882. It might even be a separate property like import.meta.preloading?

avivkeller · 2024-07-17T18:39:26Z

This sounds distinct from what is being discussed in #53882. It might even be a separate property like import.meta.preloading?

I'm not saying it's the solution do that problem, I'm just saying it was referenced, and the sources for the feature (this) are seemingly stale, so I wanted to verify they were still being worked on. (Sorry if I worded my last comment poorly)

GeoffreyBooth · 2024-07-17T20:33:22Z

I think since Deno supports this property we should add it if we can. I think we should go through the same process with the WinterCG registry that we went through for import.meta.filename, to ensure that our implementation is compatible with Deno's.

avivkeller · 2024-09-13T21:58:14Z

(AFAICT there are no specific issues/PRs blocking this issue)

ljharb · 2024-09-14T03:06:09Z

The block is because of the still unresolved request for changes on the PR; it should remain.

avivkeller · 2024-09-14T10:22:52Z

The blocked label is specific for issues/PRs blocking something, so I was trying to declutter. Feel free to re-add if needed.

ljharb · 2024-09-14T14:08:07Z

I dont have the ability to re-add it; it’s also blocked on WinterCG though.

aduh95 · 2024-09-14T14:12:00Z

it’s also blocked on WinterCG though.

Is it? AFAICT import.meta.main is already defined in https://github.com/wintercg/import-meta-registry, not sure what other kind of input we should expect from WinterCG.

ljharb · 2024-09-14T14:26:27Z

That’s just documentation; it’s not the same as WinterCG having agreed on an interoperable implementation.

jasnell · 2024-09-21T15:48:13Z

Correct, the import-meta-registry is intended just to document the properties that runtimes are using. It is not intended as an endorsement.

guybedford · 2024-09-24T01:10:53Z

@aduh95 as authored here is it set to true when importing the main entry point from a worker?

guybedford · 2024-09-24T01:11:34Z

And just to be clear, my previous approval still stands. I wonder if we can get an update from @jkrems?

jkrems · 2024-09-24T01:17:01Z

It still feels like an awkward design choice because of things like "can't easily wrap" but those gaps could be filled with loaders or better core APIs in the future.

If nobody else has pushed a better API in X years, there's a good chance that making it easier to write more interoperable code is worth it. Would be great to have some canonical definition of the exact semantics that can be shared across runtimes. But worst case, that's what major versions are for..?

Willing to dismiss my review here to unblock progress.

It's been 5 years. It's unlikely that a better alternative materializes.

ljharb · 2025-03-05T23:07:02Z

lib/internal/modules/esm/translators.js

@@ -66,11 +68,12 @@ function initializeImportMeta(meta, { url }) {
  // Alphabetical
  if (experimentalImportMetaResolve)
    meta.resolve = createImportMetaResolve(url);
+  meta.main = Boolean(this?.isMain);


Suggested change

meta.main = Boolean(this?.isMain);

meta.main = !!this?.isMain;

Is there a performance merit to this? or is it for brevity / for consistency? (out of interest)

Both, and it avoids a primordial.

ljharb · 2025-03-05T23:07:51Z

lib/internal/modules/esm/translators.js

@@ -80,7 +83,9 @@ translators.set('module', async function moduleStrategy(url) {
  debug(`Translating StandardModule ${url}`);
  const module = new ModuleWrap(url, undefined, source, 0, 0);
  moduleWrap.callbackMap.set(module, {
-    initializeImportMeta,
+    initializeImportMeta: isMain ?
+      FunctionPrototypeBind(initializeImportMeta, { isMain }) :


Suggested change

FunctionPrototypeBind(initializeImportMeta, { isMain }) :

() => initializeImportMeta({ isMain }) :

i believe an arrow is faster than binding

Lordfirespeed · 2025-04-08T15:50:16Z

Is it all good if I pick up from here in a new PR? It seems a bit unfair to expect @aduh95 to be keeping on top of it after 5 years 😂

nodejs-github-bot added the esm Issues and PRs related to the ECMAScript Modules implementation. label Mar 12, 2020

aduh95 force-pushed the import-meta-main branch from b6a8c89 to c7bf59b Compare March 12, 2020 11:30

jasnell reviewed Mar 12, 2020

View reviewed changes

doc/api/esm.md Show resolved Hide resolved

aduh95 mentioned this pull request Mar 12, 2020

import.meta.main #49440

Closed

devsnek suggested changes Mar 12, 2020

View reviewed changes

jkrems previously requested changes Mar 12, 2020

View reviewed changes

bmeck added the blocked PRs that are blocked by other issues or PRs. label Mar 12, 2020

esm: implement import.meta.main

382d66c

Boolean value to check if a module is run as entry point of the current process. Fixes: https://gtihub.com/nodejs/modules/issues/274

aduh95 force-pushed the import-meta-main branch from c7bf59b to 382d66c Compare March 19, 2020 14:21

addaleax approved these changes Mar 29, 2020

View reviewed changes

BridgeAR force-pushed the master branch 2 times, most recently from 8ae28ff to 2935f72 Compare May 31, 2020 12:18

mcollina mentioned this pull request Aug 19, 2020

Fixes fastify version check in ESM context fastify/fastify-plugin#102

Merged

4 tasks

guybedford approved these changes Oct 5, 2020

View reviewed changes

guybedford force-pushed the master branch from dc5a5da to 8e46568 Compare March 29, 2021 21:33

Trott force-pushed the main branch from 2d76238 to ca3ed36 Compare November 12, 2022 01:49

wojpawlik mentioned this pull request Mar 23, 2024

fix: add bin field to npm compat tarballs jsr-io/jsr#284

Open

avivkeller removed the blocked PRs that are blocked by other issues or PRs. label Sep 13, 2024

jasnell approved these changes Sep 21, 2024

View reviewed changes

LiviaMedeiros mentioned this pull request Mar 5, 2025

import.meta.main #57226

Open

ljharb reviewed Mar 5, 2025

View reviewed changes

Lordfirespeed mentioned this pull request Apr 9, 2025

esm: implement import.meta.main #57804

Open

	meta.main = Boolean(this?.isMain);
	meta.main = !!this?.isMain;

	FunctionPrototypeBind(initializeImportMeta, { isMain }) :
	() => initializeImportMeta({ isMain }) :

esm: implement import.meta.main #32223

Are you sure you want to change the base?

esm: implement import.meta.main #32223

Conversation

aduh95 commented Mar 12, 2020 • edited Loading

Checklist

jasnell commented Mar 12, 2020

aduh95 commented Mar 12, 2020

devsnek left a comment

Choose a reason for hiding this comment

jkrems left a comment

Choose a reason for hiding this comment

aduh95 commented Mar 13, 2020

devsnek commented Mar 13, 2020

addaleax left a comment

Choose a reason for hiding this comment

aduh95 commented Aug 27, 2020

guybedford commented Oct 5, 2020

jkrems commented Oct 5, 2020

aduh95 commented Oct 5, 2020 • edited Loading

jkrems commented Oct 5, 2020

aduh95 commented Oct 5, 2020

jkrems commented Oct 5, 2020

ExE-Boss commented Oct 5, 2020

Example:

Input:

Output:

jkrems commented Oct 5, 2020 • edited Loading

guybedford commented Oct 6, 2020

jkrems commented Oct 6, 2020

rektide commented Feb 25, 2021

guybedford commented Mar 8, 2021

devsnek commented Mar 8, 2021 • edited Loading

atg commented Sep 8, 2021

jkrems commented Sep 8, 2021

aduh95 commented Sep 8, 2021

jkrems commented Sep 8, 2021

avivkeller commented Jul 17, 2024

guybedford commented Jul 17, 2024

avivkeller commented Jul 17, 2024

GeoffreyBooth commented Jul 17, 2024

avivkeller commented Sep 13, 2024

ljharb commented Sep 14, 2024

avivkeller commented Sep 14, 2024

ljharb commented Sep 14, 2024

aduh95 commented Sep 14, 2024

ljharb commented Sep 14, 2024

jasnell commented Sep 21, 2024

guybedford commented Sep 24, 2024

guybedford commented Sep 24, 2024

jkrems commented Sep 24, 2024 • edited Loading

ljharb Mar 5, 2025

Choose a reason for hiding this comment

Lordfirespeed Mar 6, 2025

Choose a reason for hiding this comment

ljharb Mar 6, 2025

Choose a reason for hiding this comment

ljharb Mar 5, 2025

Choose a reason for hiding this comment

Lordfirespeed commented Apr 8, 2025

aduh95 commented Mar 12, 2020 •

edited

Loading

aduh95 commented Oct 5, 2020 •

edited

Loading

jkrems commented Oct 5, 2020 •

edited

Loading

devsnek commented Mar 8, 2021 •

edited

Loading

jkrems commented Sep 24, 2024 •

edited

Loading