[Feature] Make package.json JSON5 / JSON with comments

[bgotink]

• I'd be willing to implement this feature
• This feature can already be implemented through a plugin

Describe the user story

As a package author I want to put comments in my package manifests, e.g.

{
  "peerDependencies": {
    "@angular/compiler-cli": "^8.0.0",
    // Keep this in sync with the version required by @angular/compiler-cli
    "typescript": "~3.4.7"
  }
}

See also: yarnpkg/yarn#178 and others.

Describe the solution you'd like

Parse the package manifests using JSON5 or another library that parses JSON with comments

Describe the drawbacks of your solution

• The package.json becomes unparseable by other package managers like npm or tools that don't support the extended JSON syntax.

  That's a big downside due to the number of tools that parse package.json files (e.g. every tool that can be configured from within the package manifest) but as it's completely optional I personally don't think this is a blocker.

• We'd need to clean this up at publish time (but we already do this, so that shouldn't matter much)

• Writing the package manifest to disk becomes a lot more complicated: do we remove comments on the line before a removed dependency? do we move comments around if we sort the dependencies?

  An easy solution would be to say "we just write JSON, i.e. without comments, so it's up to you to ensure the comments remain" which might be a good MVP to start with but it doesn't seem like a good idea for the long run.

Describe alternatives you've considered

Adding comments out of place, e.g.

{
   "//": "Keep typescript in sync with the dependency listed in @angular/compiler-cli",
  "peerDependencies": {
    "@angular/compiler-cli": "^8.0.0",
    "typescript": "~3.4.7"
   }
}

but this dirties the package manifest: these extra values can get published and they require changes if more comments are added (no duplicate keys are allowed, so you'd have to use // <counter> instead)

[arcanis]

One significant tool that doesn't support JSON5 is ... Node itself. Things like the main field would break, and potentially more - for example there's a chance that we get to configure the module loaders via the package.json files (which would be amazing, since we wouldn't have to use yarn node anymore to run scripts). It wouldn't be possible with a JSON5 file.

[bgotink]

My first reaction was "but node doesn't get to parse the json5 version of the file, does it?" but of course in a multi-workspace repository the package.json does get used at development time.

Ergo this is a no-go on yarn side without support upstream in node, but this is still a feature that I would really like to have. To quote from yarnpkg/yarn#178 (comment):

A dependency manifest (and even more so package.json) is a remarkably comprehensive, accessibly concise, syntactically enforced and implicitly maintained piece of humanly consumable documentation. It is the doorway into understanding a new project. That comments are not supported is not merely a minor omission but an existential misrepresentation.

(emphasis added)

[jack-sf]

Wouldn't it be better to have a different file like package.cjson that is then compiled to package.json on yarn install or something ?

[arcanis]

It could (in fact, you can already have this behavior if you use the afterAllInstalled hook to implement the conversion), but I don't think we'd do that by default.

[arcanis]

I'm going to close this since the Node compatibility issue cannot be easily solved at the moment.