Proposal: Remove ESM/CJS duality from code samples in API docs
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 45/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- javascript
- Domain
- documentation
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.
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
- Dominant language
- JavaScript
- Stars
- 122k
- Forks
- 37.4k
- Avg merge
- 4d 4h
- Merged PRs (30d)
- 276
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from nodejs/node
-
doc
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
-
build
Difficulty 1/5 Under an hour Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
-
Difficulty 1/5 Under an hour Newbie friendliness 90/100
-
feature request
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Similar issues
-
bug customer-eng Durable Agents Inngest status: needs triage
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
optimization optimization:agents-md-curator
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
githubnext/gh-aw-cao#13475 ·
-
[BUG]: "Clear All" in Settings doesn't clear the saved analysis, old data comes back after reload Openbug
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
AOSSIE-Org/OrgExplorer#253 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
oxc-project/oxc#26944 ·
-
ai-observability bug team/ai-observability
Difficulty 2/5 1-3 hours Newbie friendliness 78/100