Proposal: Remove ESM/CJS duality from code samples in API docs

Offen

#65,536 erstellt am 25.8.2026 3 Kommentare 18 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit: 5/5
Geschätzter Aufwand: Über eine Woche
Anfängerfreundlichkeit: 45/100

Issue-Typ: Dokumentation
Klarheit: Größtenteils klar
Aktivitätsstatus: Aktiv
Tech-Stack: javascript
Bereich: documentation

Rechercherichtung

Überprüfe die Beispiele unter /doc/api und erfasse die Codeblöcke mjs und cjs, wobei du Fälle notierst, die speziell das CommonJS-Verhalten demonstrieren. Bestätige den Umfang und die Konvention ESM als Standard mit den Maintainers, bevor du geeignete Beispiele in js-Blöcke zusammenführst. Als abgeschlossen gilt die Aufgabe, wenn doppelte Beispiele entfernt wurden und CJS-spezifische Demonstrationen weiterhin korrekt sind.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

discuss doc

Since the introduction of ESM to Node.js core, we have been providing togglable ESM/CJS code examples in the API docs.

These examples differ only in the lines of code containing core imports, but the entire codeblocks need duplicating due to the limitations of the web renderer, leading to whole reams of duplicated cruft across /doc/api. The documentation space is extremely patchy as to which examples are just ESM, just CJS, or both. We occasionally get very kind contributors submitting PRs to double-up existing CJS-only code examples, but these are not good uses of reviewer time.

Almost invariably, it is incredibly obvious as to how to convert an ESM import from a builtin module into a CJS import, or vice versa.

I suggest that we:

get rid of ```mjs and ```cjs blocks in favour of a single ```js block
canonicalise ESM imports as the example paradigm of choice, unless a example is specifically demonstrating something CJS-specific

Vorherrschende Sprache: JavaScript
Sterne: 122k
Forks: 37.4k
Ø Merge: 4 T. 3 Std.
Gemergte PRs (30 T.): 279

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
Forken Sie das Repository und arbeiten Sie in einem Branch.
Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus nodejs/node

Stream.prototype.forEach will block in first promise in queue before read more chunk Offen

doc

Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 65/100

nodejs/node#66106 · Erstellt am 18.9.2026
nodejs 26.8.2 fails to build with clang/LLVM Offen

build

Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 88/100

nodejs/node#66076 · 2 Kommentare · Erstellt am 17.9.2026
`TextEncoder.encodeInto()` underfills the destination for some non-ASCII text Offen

Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 84/100

nodejs/node#65994 · 2 Kommentare · 2 Reaktionen · Erstellt am 11.9.2026
worker: `messageerror` listeners remain during `exit` Offen

Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 90/100

nodejs/node#65782 · Erstellt am 04.9.2026
[`util.styleText`] Allow `text` param to be any scalar value (ex. `number`, `bool` etc additionaly to `string`) which will be casted internally to `string` Offen

feature request

Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 68/100

nodejs/node#63841 · 1 Kommentar · Erstellt am 10.6.2026

Alle Issues in nodejs/node