Official ESM Support Mega Issue

[mdonnalley]

We recognize that our half-hearted support of ESM up to this point has been a point of frustration for many but we're excited to announce that ESM support in oclif has officially become our top priority 🎉

You can view our progress on the public Github Project.

Please feel free to comment with any requests or ideas. And, as always, we're open to contributions from the community!

See this comment for latest update

[pinko-fowle]

Node itself is quite frustrating with nodejs/node#34049 meaning that there's no good way to run ESM executables in Node.

Thank you all for taking this up! I'm trying to integrate some usage of zx which I thought was going to make life easy, but it's been a day of heartbreak trying to get over to "type": "module".

[jenkin]

A fork of the official oclif starter kit (latest version) with full ESM support and all update dependencies / clean audit: https://github.com/jenkin/oclif-esm-starter (see also #1016).

[mdonnalley]

Hey everyone!

We just released @oclif/core@3.0.0-beta.7, which fully supports ESM plugins as well as interoperability with CommonJS plugins (as well as a few other breaking changes)

The docs here attempt explain what's required to migrate your plugin to ESM. As with all documentation, it can be difficult to see where you've left things out that you assumed others understood - so please let us know if there's anything that should be added. Also it's important to note that those docs do not attempt to explain everything that would be required to migrate your plugin to ESM (e.g. updating file paths, etc.) but only attempts to explain the steps that relate specifically to ocilf.

Also, as of version 3.13.1-beta.0, the oclif version CLI now supports generating ESM CLIs/plugins - just select ESM when it prompts you to select the module type. The generated CLI/plugin is based off of https://github.com/oclif/hello-world-esm

Lastly, one note on linking ESM plugins: As @pinko-fowle alluded to in this comment, node does not work with ESM executables if the --loader=ts/node-esm option is not provided. This makes auto-compilation of linked ESM plugin impossible. If the ESM plugin is linked to a CJS plugin, the only option we have is to fall back onto the compiled source. This means that you must compile the plugin first before executing a command. If the ESM plugin is linked to another ESM plugin, then you can enable auto-compilation by setting NODE_OPTIONS="--loader=ts-node/esm" in your environment, otherwise it will fallback on the compiled source.

These changes are still in beta so please give it a try and let us know if there's anything we can do to it improve it. Thanks!

[mdonnalley]

UPDATE: after encountering issues with linking ESM plugins in a production environment we've decided to not support auto-transpiling linked ESM plugins at this time. We're hoping that some potential forthcoming changes to node will allow us to support this feature again. In the meantime, we recommend running yarn tsc -w in a separate terminal to ensure that all your changes are compiled before executing a command.

[mdonnalley]

Closing this since we just released 3.0.0. See the docs for more info about ESM support. As always feel free to point out anything we might have missed in the documentation or create a new issue for any issues you encounter