es-module import syntax

[travi]

i normally use es-module syntax for imports in my usage examples, but i love the idea of writing the example as a separate file that is lintable/testable. since es-module syntax isn't yet part of the language, it makes sense why it wouldn't work out of the box. any chance there is an existing way to apply babel-register or similar to support things like this?

[wooorm]

Right! Well, PRs welcome! We’re using regexes here for the detection so that should be updated. And for the registration, there’s probably a way to turn the experimental modules flag on?

[travi]

the regex seems like a reasonable change, but getting the module flag turned on is certainly the first hurdle. since i'm using remark-cli, i'm not sure how to enable it. i didnt expect it to work directly with remark-cli, but trying that results in Error: Unknown option --experimental-modules, expected: ....

do you have a suggestion for that piece?

[wooorm]

do you have a suggestion for that piece?

My suggestion would be to wait before modules are stable and land 🤷‍♂️ I understand it’s a nice feature to have, but as it hasn’t landed, it’s subject to change!

[travi]

thats fair to an extent. the reason i'd like for my usage examples to use es-module syntax, though, is because that the intended use is to support bundling with either webpack or rollup. both of these expect module syntax for more optimal bundling, so i'd prefer to not de-optimize the examples.

i'm certainly not using the flagged node behavior directly, but instead through babel. the transpilation buys me some stability, even if the native implementation changes.

i assume there isn't currently a way to apply a babel config before the verification that the file is valid, but use the original source in the inclusion into the markdown? would such a feature be possible? i could see how something like that could be pretty disruptive, but figure its worth at least asking about.

[wooorm]

You can use Babel, but that doesn’t mean your users use it, or that the code you run in Babel works their environments!

I’m also wondering if adding babel even works, we’re just loading the script with require internally, and from what I hear modules and requires won’t be able to mix. So I think it would mean a whole big rewrite 🤔

Maybe a fork of this plugin that uses babel is the way to go? 🤷‍♂️

[travi]

or that the code you run in Babel works their environments!

when publishing packages, i always include both a common-js bundle as the main property of package.json and an es-module as the module property. node always consumes the one defined as main, but bundlers that consumers may be using in their project, like webpack or rollup know to use the one defined as module. this ends up being a very effective approach, and consumers don't really even have to know what the tools are doing under the hood because it just works. the project where i'm using remark-usage first is an example of that approach if the details would be helpful: https://github.com/travi/javascript-scaffolder

with that said, a consumer of a package can import from a package built this way using either require or import, but using import obviously requires that they are transpiling in most cases on their end. i prefer to document using import since it encourages the approach that gets the most benefit from tools that can optimize the code further, or at least makes it clear that i've built the package in a way that is compatible. if i werent documenting using import, i would at least like to document the approach with require and the way with import, so that remains limited.

nothing wrong with the current situation, mostly just that it limits options. i can certainly understand ways that adding a transpilation step would not be a small change, so i was mostly curious if it was something you were considering or not on the radar. from the outside, the ast manipulation of babel and that of unified seem aligned enough that i wouldnt have been surprised if you were already considering it somehow, but can understand if thats not the case.

since i dont have much detail to offer without investigation, i'm not sure how valuable this would be, but i do think that there is a way with babel to apply babel-register (the piece that does the transpilation) only if available in the project. beyond the conditional transpilation, the other benefit to that would be that it uses the version provided by the consumer of, in this case, remark-usage instead of introducing a dependency directly by this package that can conflict with versions already provided by the consumers.

thanks for your continued input, but i can understand if you close as out of scope for now.

[wooorm]

Wellllll! Thanks for your patience. It took a bit to rewrite everything with Babel, and then the ES Modules weren’t that hard.

I’ll release this soon.

[travi]

outstanding! thanks so much! i'm excited to give it a try