docs: editorial pass on the Node compatibility page#3241
Conversation
| Deno is Node-compatible: most Node.js projects will run in Deno with little or | ||
| no change. You can import npm packages with the `npm:` specifier, use Node's | ||
| built-in modules through `node:` specifiers, and keep your existing | ||
| `package.json`. No `npm install` step is required before running your code. |
There was a problem hiding this comment.
No
npm installstep is required before running your code.
I'm not sure it's worth highlighting here - there are edge cases where this breaks. Similarly introducing npm: specifiers in the first sentence will be more confusing than helpful. Let's rewrite this whole intro - use concrete examples
There was a problem hiding this comment.
Agreed, going further than an intro fix: three ground-up rewrites are being prepared on separate branches for comparison (A: example-led walkthrough threading one real project through the page; B: compatibility lookup with a status-overview table per surface; C: task-oriented recipes with inline troubleshooting). All three reuse this PR's verified facts and fixed snippets, keep the linked anchors, and follow the concrete-examples-first direction. Branch links coming shortly; this PR holds as the fact-checked baseline meanwhile.
1 participant
The Node compatibility page had accreted rather than been edited: a Quick
start section restating the intro, the global-cache fact stated four times,
CommonJS support sprawled across seven overlapping subsections, and
inconsistent permission flags (-R -E in one example, "just use -A" in the
next). This pass restructures without losing content: CommonJS support is
now four coherent subsections, node_modules is consolidated around its
mode table, and roughly 270 words of repetition are gone while every unique
fact stays.
Running the snippets surfaced real staleness and one actual bug: the
process.versions.deno sample said 2.0.0 (now 2.8.3), a bare-import error
message no longer matched Deno's current output, the deno install output
format had changed, and the import-CommonJS example imported ./greet.js
while the file it creates is greet.cjs, so it never worked as written. All
fixed against live runs on 2.8. Permission flags are standardized on
minimal short forms. Every heading with inbound links (commonjs-support,
private-registries, npmrc-configuration, using-npm-packages) keeps its
exact text, and the private-registries section is untouched.