Examples of ES Modules

[Sequoia]

I have been attempting to follow the evolving discussion around ESM support in Node.js, but I'm very confused about some fundamental points, and I suspect others are as well. In particular, I can't figure out whether import only operate on files with mjs extensions or work within files with mjs extension. Statements like this unfortunately do not clear it up for me:

import statements will only support files with an .mjs extension, and will import only ES modules, for now.

Also: module.createRequireFromPath. I have no idea how I'd even start to use this method. I'm the "javascript expert" at my work but I struggle to explain the future (or present state) of module loading in
JavaScript so I'm keen to understand this better.

🙏 Request: Is a list of concrete examples in the offing? A blog post, a repository, or a gist of runnable examples would be very helpful.

[Sequoia]

Perhaps these features are just too new for external consumption. In any event, my suspicion is that answers to a lot of my questions are obvious to those who have been discussing this for months & years. I'm writing to say "answers to these questions are very much not obvious to JS users who are not part of the conversation on an ongoing basis."

[devsnek]

The current design isn't usable right now, we're still building it.

To answer your question, import can only exist in es modules, and right now import only imports es modules (identified by .mjs), not json or native addons or anything else.

[MylesBorins]

It is also worth mentioning that the phases identified I'm the doc, and the current capabilities list only affects the implementation in our ecmascript modules fork, it does not yet have any affect on the experimental modules shipping in core, although the plan is that the new implementation will eventually replace it

…

On Thu, Oct 25, 2018, 9:54 AM Gus Caplan ***@***.*** wrote: The current design isn't usable right now, we're still building it. To answer your question, import can only exist in es modules, and right now import only imports es modules (identified by .mjs), not json or native addons or anything else. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#210 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAecVxQZ5hVVd9_xamVoFmTaoT6Zd0awks5uocKfgaJpZM4X6UfD> .

[GeoffreyBooth]

And the items listed in the phases doc are not the entirety of what we plan to build. The features list in the README is an indicator of where we'd like to end up.

[jkrems]

I'll happily throw a +1 behind "having [eventually] runnable examples" in addition to the docs. I know that I have a much easier time understanding an explanation if it comes with "for example: X".

[bmeck]

I'd rather not add "eventually" runnable examples only to remove them. It would just add to confusion. This like if node_modules is supported or not change expectations for how the examples work.

[jkrems]

Sure, happy to keep it at "straight-up runnable examples" and extend as we build agreement.

[Sequoia]

I'd also be happy with "not-runnable examples" that simply illustrate what these APIs will look like. e.g.

foo.mjs

// ✅ this will work; add & subtract are immediately available
import add, subtract from './my-maths.mjs';

// ❌ this will not work: can only import .mjs modules
import add from './cjs-modules/my-maths.js';

// ✅ This will work: add is immediately available
const add = module.createRequireFromPath('./cjs-modules/my-maths.js').add;

// ❌ this will not work: can only import by file path
import add from 'my-maths';

bar.js

// ❌ this will not work: import will only work WITHIN mjs files
// NB: if this "works" for you, it's probably because you're using babel or webpack, it is NOT native behavior
import add from './my-maths.mjs'

my-maths.mjs

// ❌ this will not work: must use `export` in mjs files
module.exports = { add : (x, y) => y +x };

This is what I'm looking for. Some readable examples of what these APIs will look like, how we currently expect them to work, for onlookers like myself. Without this, the best I can do is wait til the feature is actually implemented and shipped and look for examples at that point (possibly not a bad option).

Is this worthwhile? Will it cause people to jump ahead too far or get an incorrect impression of what might get shipped?

[devsnek]

these just look like unit tests we should have anyway. if people need to look at broken code for some reason we can point them to the test directory.

[Sequoia]

if people need to look at broken code for some reason

The reason is to understand that what things I do today (e.g. require('foo')) will not work in the new system, and which parts of the new system I can use everywhere vs. which parts are limited to the new system. I may be alone in finding such examples useful but I doubt it.

As for unit tests, sure, but:

1. It sounds like its premature for those as not everything is implemented and
2. These are not a great way to get a brief overview of how this new-fangled module stuff works, especially since (I assume) it's likely that in the context of unit tests you may be consuming these APIs in some non-standard way for the purposes of testing.

[devsnek]

we need to just write the implementation and then write good docs to go with it. having a bunch of random code isn't helpful without explanation, and it certainly won't make an unfinished implementation any more usable.

I think this just falls under keeping doc/esm.md updated.

[GeoffreyBooth]

illustrate what these APIs will look like

This is very much still up for debate. We’re trying to figure out a way to allow import and export statements in .js files that works for everyone. (Not to combine CommonJS and ESM in the same file, but to allow import and export statements in .js files like is currently supported in browsers.) See #150 and #160. This also relates to the design for loaders; and a discussion farther down the line of what should be the default, what should be enabled via configuration, and what should be possible via loaders. This is all still very much up in the air.

If I were you I would write standard ES2015 JavaScript that follows the syntax shown on MDN, builds with existing tools and possibly runs in browsers (aside from requiring Node core modules and packages etc.). I think it’s likely that any ESM JavaScript that runs in browsers will also run in Node, as one of our top goals is browser equivalence.

[Sequoia]

It sounds like the answer is "it's too early to make any concrete statements or provide examples– wait until it's implemented & check back then." I'm OK with that. 👍 I got here from a tweet from @MylesBorins and it sounded like there was some useful update for node users. I did not understand what the update meant so I came here. It sounds like in it's current state the proposal is not ready or useful for consumption beyond node-core contributors. I'll treat this as "way too early to look at" and check back in another year. Thanks!

[GeoffreyBooth]

check back in another year

Hopefully not a full year 🤞 😄