Experimental Status

[guybedford]

Currently the entire modules implementation is marked as experimental status.

With the completion of the major backports to v12, we effectively have a natural stability for the primary features of the implementation.

If we make this natural experimental status explicit by changing the experimental status of the entire implementation, this will help give users confidence in upgrading their libraries and applications to using modules in Node.js.

Individual modules features can still be retained as having experimental status. These include:

• All features with experimental flags
• Loaders

The following newer features for modules may or may not be suitable to remain in experimental status:

• Top-level await
• CommonJS named exports
• Subpath imports
• Subpath patterns

Perhaps we can put some time to discussing the details of this stability change further.

[bmeck]

I think the only thing I might want is more tests for Subpaths really. Should probably split that up into much more granular topics (exports, imports, conditions, patterns, require() [no tests for exports?] /import)

[ljharb]

Are patterns backported to 12 and released? (i think imports is already in 12, right?)

[MylesBorins]

@ljharb patterns and cjs auto named exports are not backported yet but we have one last Semver-Minor for 12.x to make sure we can land that. Just letting it bake on 14.x / 15.x a tiny bit more

[GeoffreyBooth]

In my mind the question is whether there are any still-unfulfilled goals we have related to ES modules that might necessitate breaking changes to the implementation we’ve built. I think the only outstanding goals are hot module reload and instrumentation; is there anything else I’m forgetting? If not, both of those are part of loaders, which I’m sure will stay experimental, so it seems fine to “release” the rest.

[ljharb]

The only other thing I can think of is node-style resolution, but it seems clear that some of the node collaborators here would block on it, so it’s likely not worth the effort to discuss.

[GeoffreyBooth]

The only other thing I can think of is node-style resolution, but it seems clear that some of the node collaborators here would block on it, so it’s likely not worth the effort to discuss.

Yes. But that can be added at any point without it being a breaking change, so it’s not a factor in whether we keep the status as experimental.

[robertdumitrescu]

I definitely agree that ESM modules should not be experimental anymore. Mocha/Chai/Nyc/C8 frameworks are all waiting for that to go Stable to implement them. Currently for coverage data, you need to do loads of hacks in the IDE's to get it working with ESM modules.

[MylesBorins]

It might be a good idea to create an enumerated list of the "features" that make up ESM (as Guy did above), determine the status of each of those features, and determine which of those features need to be stable to consider ESM as a whole stable. It would likely also be a good idea to separate the pure ESM features from package features effecting both ESM + CJS

Looking at the list below it would seem to me the only thing I would want to see be a bit more stable before flipping ESM itself to stable would be to have commonjs named exports bake a bit more.

For the Package related features we actually have a stability level for each feature and I've opened a PR to stabilize all features aside from subpath patterns which likely need a bit more time to bake.

---

ESM only

Stable:

• ESM loader
• ESM named exports
• node: imports
• data: imports
• import.meta
• builtin modules
• createRequire
• Resolution algorithm

Experimental:

• Top-level await
• CommonJS named exports
• JSON modules
• WASM modules
• Loaders
• experimental specifier resolution

---

Package Features (esm + cjs)

stable:

• type: 'module'
• --input-type
• package exports / imports
• conditional exports / imports
• Subpath exports / imports
• exports sugar
• nested conditions
• user conditions

Experimental:

• Subpath patterns

---

Unsolved Features:

• VM ESM API
• Hot Module Reload
• Module Cache
• Instrumentation

[SimenB]

Are the vm ESM APIs not part of this stabilisation discussion, or just forgotten?

EDIT: I see it was added to the comment 👍

[bizob2828]

This is def a selfish response but I worry the experimental flag will be removed before there is a way to instrument esm.