nodejs / nodejs/node

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

Open
#65,536 3 comments 18 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

discuss doc
Dominant language
JavaScript
Stars
122k
Forks
37.3k
Avg merge
4d 2h
Merged PRs (30d)
283

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the examples under /doc/api and inventory the mjs and cjs code blocks, noting cases that specifically demonstrate CommonJS behavior. Confirm the scope and ESM-as-default convention with maintainers before consolidating eligible examples into js blocks. Done means duplicated examples are removed while CJS-specific demonstrations remain accurate.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.