doc: move package config docs to separate page

[aduh95]

This part of the docs aims to contain documentation regarding package configuration that covers both ESM and CJS realms.

Refs: nodejs/modules#539

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[nodejs-github-bot]

Review requested:

• @nodejs/modules

[DerekNonGeneric]

@aduh95, breaking pre-existing links is not a viable path forward — see #34663 (review). Would you mind figuring out how we will be redirecting users before continuing?

Some possibilities:

• 301 redirects
• Links to the new section locations below headings
• Something else

[aduh95]

@DerekNonGeneric thanks for the input, I agree that is something important to have in mind.

breaking pre-existing links is not a viable path forward

IIRC, it's considered OK to break things for experimental features, and this PR is focused mostly on topics in the esm.md docs (still experimental at the time of writing). So your comment is about the Addenda: Package manager tips and Core modules sections of modules.md, is that correct?

Links to the new section locations below headings

Just to be clear, are you referring to having something like Section moved to [package config page](…). for those sections? That could work for me.

[DerekNonGeneric]

[…] it's considered OK to break things for experimental features […]

That's not entirely true. The APIs that are marked as experimental are subject to change (breaking), but there is no justification to entirely break the documentation page links.

So your comment is about the Addenda: Package manager tips and Core modules sections of modules.md, is that correct?

These shouldn't be entirely broken links, correct.

Just to be clear, are you referring to having something like Section moved to package config page. for those sections? That could work for me.

We have done something to this effect in the past, so it may be seen as more of an acceptable approach to take here. If you're able to find prior art similar to this in the actual API ref docs, that would be even closer to what could be seen as more acceptable.

[aduh95]

301 redirects

I've done some digging about that, turns out that wouldn't work here: the hash part of the URL (E.G.: #modules_core_modules) is not transmitted to the server, this information is only available at the client side.

An "automatic" redirection would require involving some hacky JS stuff, I doubt that's a road we want to walk.

Anyway, I have added redirection links in my last commit, PTAL.

[guybedford]

@DerekNonGeneric the modules documentation has not yet stabilized and we reguarlarly break the links still. I do not see why this PR should be treated differently from that perspective. Agreed changing ESM doc links should start to be blocked soon though.

[guybedford]

This seems like a good start. I'd be happy to land this given the comments, and then iterate on improving the esm and package config docs sections further individually. For example package configuration being a more comprehensive guide to new users eg questions like "CommonJS or ES Modules?" being discussed - "use CommonJS if...", "use ES Modules if..." etc.

[aduh95]

Based on comments from @DerekNonGeneric and @guybedford, I have removed the changes in modules.md from this PR. I have also added HTML anchors and links to the new doc to maintain backward compatibility with links to the current docs. PTAL.

[DerekNonGeneric]

@aduh95, do you have an opinion on #34748 (comment)? 👀

[DerekNonGeneric]

I think it's important for this page to not imply that everyone using this file is expected to become a package author or have any remote interest in configuration of a package for any purpose whatsoever.

It may be called package.json, but I guarantee there are folks who have absolutely no interest in publishing a package and are solely interested in enabling ESM for .js extensions or adding conditional exports for the convenience of the bare specifiers for use in their apps.

That said, I think we should be cautious about the wording that is used here and try to genericize the term package.json to mean project manifest or similar. I hope that doesn't seem like an unreasonable stance on the matter but feel free to debate. :)

[DerekNonGeneric]

/cc @nodejs/modules-active-members as this is a pretty substantial change

[DerekNonGeneric]

I would like to ping a few folks who are involved in the development of the three main package managers who obviously use this file for packagey-type things. My impression is that it would be best to keep this page as agnostic as possible, although perhaps alluding to the fact that package.json is shared by various tools would be of some value here too.

Looking to gather some opinions if we've achieved that well enough or what some next best steps would be.

/cc @ruyadorno @shellscape @arcanis

Mainly curious to know if there are things that should belong on this page that we should make clear as it would be the first time Node.js would have a page dedicated to this file. Thanks in advance!

[DerekNonGeneric]

I think this page still needs the "experimental API" documentation warning.

[arcanis]

Nice - I'd probably just add a section mentioning that this only covers the fields that Node understands, and maybe add a link to the Yarn / npm documentations for those that belong to package managers. It might help some less advanced users that would find this page through SEO.

[GeoffreyBooth]

Elsewhere we had discussed making this page about package authoring in general, not specific to just package.json. That way the page is free to include sections that aren't necessarily package.json fields.

Could we maybe call this page Modules: Packages? And the introduction could explain what a package is, first, before explaining what package scope is.

[aduh95]

Nice - I'd probably just add a section mentioning that this only covers the fields that Node understands, and maybe add a link to the Yarn / npm documentations for those that belong to package managers. It might help some less advanced users that would find this page through SEO.

@arcanis right, I mean to do that in a following PR that documents package.json fields that are supported by Node.js.

Could we maybe call this page Modules: Packages? And the introduction could explain what a package is, first, before explaining what package scope is.

@GeoffreyBooth That seems like a good tradeoff to me. I'm not sure what difference there is between a package scope and a package though.

[GeoffreyBooth]

I'm not sure what difference there is between a package scope and a package though.

A package is what's listed in package.json "dependencies", like "lodash". Within a package, i.e. within ./node_modules/lodash, there is at least one package scope, which is the folder that contains the package.json file: ./node_modules/lodash/package.json and all subfolders until a subfolder with another package.json file is found.

So for example if there was ./node_modules/lodash/dist/package.json, then ./node_modules/lodash/dist would be a different package scope than ./node_modules/lodash. It's similar to JavaScript when you might define a function within the body of another function: the “child” function has its own scope inside the parent function's scope.

[ruyadorno]

I also think it's a good idea to loop in the folks from @nodejs/package-maintenance WG

[aduh95]

Rebased on master to solve merge conflict.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/32967/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/32969/

[guybedford]

Thanks @isaacs for volunteering here, I just wanted to ensure there is some follow-through here that's all so things don't get dropped, not trying to be difficult and certainly didn't mean to make work for you either. I'm happy to PR my own previous comments as well further so sounds like we are good to go here then.

[DerekNonGeneric]

Landed in dbc5c17

[MylesBorins]

This PR doesn't land cleanly on v14.x. Before we backport I think it would be a good idea for us to ensure all the follow up PRs have been landed so this change gets released in it's best possible form.

Thoughts?

[guybedford]

Yes, I agree we should rather we wait a little on the release of this docs work until we've completed the subsequent update PRs to a point where the majority of feedback has been incorporated and we are happy with the final state. Specifically landing #34970 and any other follow ups mentioned in this PR.

[guybedford]

PR for the outstanding feedback here created in #35370.