Embrace ESM in Node examples

[Josh-Cena]

This came out of mdn/content#13113 (comment) and is in some sense related to #143.

After Node 12 EOL, all LTS Node versions support unflagged ESM (short for ECMAScript modules). This replaces the legacy CJS (short for CommonJS) module system (although the latter is not going away either).

The interoperation between CJS and ESM in Node has been a long-standing issue and is widely regarded a pain point of Node. In summary: if the current module is CJS, it can't import anything that's ESM without using dynamic import (which is async and therefore can't be at the top level, unlike require which is sync); if the current module is ESM, it generally can import CJS the same way as before, although it may not be able to import all named exports, but have to import the entire module.exports as default import.

The fact that CJS can't import ESM means that as soon as your dependency is ESM-only, you either have to pin your dependency to an older version, or you have to re-structure your code to accommodate an async dynamic import, or you have to convert your own codebase to ESM. These days, more and more dependencies are migrating to ESM. I have written some more motivation here: facebook/docusaurus#6520. Since that's tied to a real-world project, it would offer more insight into how it impacts production.

To maximally ensure forward compatibility and avoid confusion from new users, I suggest MDN code examples embrace ESM as well. Due to the simple nature of our code, it shouldn't take much besides converting require to import and module.exports to export. If possible, we can also add a page explaining the difference between CJS and ESM and how they interoperate—I haven't seen many great resources out in the wild.

cc @teoli2003 @hamishwillee @mdn/yari-content-javascript

[teoli2003]

How big would this be? I have looked for require( and module.exports. It looks like about 30 to 50 pages would be impacted.

[Josh-Cena]

Updating the code itself would probably be around 30 pages and easily actionable. Writing an explanatory paragraph/page would be more significant.

[tshemsedinov]

Current state of CJS/ESM in node.js:

• All LTS versions supports ESM as you said
• All node.js internals uses CJS because it has features not implemented in ESM (poorly-documented and undocumented, for example caсh manipulations)
• Projects in industry moves to ESM slowly
• Some of npm libraries supports both, some supports only CJS but I do not know any library supported solely ESM (I believe they are but it is a rare cases).
• Node.js docs has cases for both CJS/ESM and even they have "switch-control" on each example to see selected one.

We can provide both cases in all examples in MDN and even more: use prefixes + submodules like this:
import * as fs from 'node:fs/promises'; or
const fs = require('node:fs/promises');

[tshemsedinov]

@Josh-Cena @teoli2003 please see updates with both module systems in proposed example: mdn/content#13113

[Josh-Cena]

I do not know any library supported solely ESM (I believe they are but it is a rare cases).

Chalk (and at least half of Sindre Sorhus' packages), Remark and its entire ecosystem, node-fetch. If you've been in the ecosystem in a while you would have heard a lot of people being confused why their project stopped building after a version bump.

caсhe manipulations

Indeed, ESM doesn't have cache manipulation but we don't need that. ESM doesn't have stable VM modules but we don't need that. ESM doesn't have stable loader chains but we don't need that. I think for the purpose of the tutorial the ESM features are complete enough.

I don't think we have the capacity to maintain two sets of documentation either. We'd rather go with ESM by default unless there's something clearly not working in ESM—which there's none, and that's why many packages believe they should push people to use ESM. The only reason many packages are not doing so is because their users are lazy (sorry for the harsh word) and don't want to spend the time migrating.