Create README.md

[dfabulich]

Copied and pasted from the old documentation for --experimental-specifier-resolution

[dfabulich]

@GeoffreyBooth

[GeoffreyBooth]

Does that example actually work? I think the loader covers specifiers within code, like import statements in your file, not the argument passed to the node binary on the command line.

(I know that that was the example in the old docs but I think it was either wrong or misstated the intent of the flag.)

Regardless, the example should show an import statement like import foo from './foo'; // fails without this loader.

[dfabulich]

I have no idea!

I started pulling on this thread by reading https://nodejs.org/en/blog/announcements/v19-release-announce/#custom-esm-resolution-adjustments

Then I read nodejs/node#44859 which also told me nothing about what this custom loader does.

I was about to file an issue that said "what does this custom loader actually do? It's not documented at all"

But then I thought, "oh, I know, I'll just read the docs of the old thing that it got rid of," and I just assumed that this thing did the same as the old thing.

If it doesn't do the same thing as the old thing, then I really have no idea what this loader does. I thought I understood --experimental-specifier-resolution=node, but if its documentation was wrong, then I'm totally at sea here, and, I'm sure, so will all other users who try to read the ESM docs and figure this out.

[dfabulich]

FWIW, I cloned the repository, and did this:

$ cd /tmp/loaders-test/commonjs-extension-resolution-loader
$ npm i
$ echo "await 1; console.log('hi');" > index.mjs
$ node --version
19.0.0
$ node --loader=./loader.js index
(node:5170) ExperimentalWarning: Custom ESM Loaders is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
hi
$ mkdir subdir
$ echo "await 1; console.log('hi');" > subdir/index.mjs
$ node --loader=./loader.js subdir
(node:5200) ExperimentalWarning: Custom ESM Loaders is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
hi

Sooo I claim that the old documentation is at least kinda sorta applicable? And the README I'm proposing isn't entirely wrong.

But, just to be sure, what do you think this loader does???

[GeoffreyBooth]

See also https://nodejs.org/api/cli.html#ecmascript-modules-loader-entry-point-caveat.

The intent of this loader is to enable import specifiers like this:

import foo from './foo'; // Where './foo' is ./foo.js or ./foo/index.js etc.

Instead of needing to write './foo.js' or './foo/index.js' or whatever the explicit path and filename is.

[dfabulich]

👍 Done. I think this is ready to merge.