Dependencies (package.json [dev]Dependencies) cannot be commented (locally in manifest)

Which @angular/* package(s) are relevant/related to the feature request?

common

Description

Dependencies of an Angular application are specified in the dependencies (and devDependencies) key of package.json, as documented in Workspace npm dependencies. This structure is inherited from npm, and with it comes a limitation which has been known for a long time and discussed in more than one place.

While the dependencies can be specified one per line in a readable way, it is (basically - hacks ignored) not possible to add a comment about a given dependency on the same line (or on the line above). This limitation itself comes from the format used by npm, JSON.

There are many reasons to comment dependencies. I work on a single Angular project which is not huge, but we have well over 30 direct dependencies, and I have hit problems which could have been avoided or largely mitigated by simply commenting dependencies, more than once just during this quarter. For example, today I needed to add a version constraint on our dependency on @types/node to workaround DefinitelyTyped #55430, and it already looks like that constraint may become unnecessary in a matter of days thanks to an upstream fix. But since I couldn’t justify it right in the manifest, that constraint could remain unwarranted for a long time because no one wants to take a chance. Other reasons to comment a dependency include indicating that:

• it should be removed
• it should be updated (but there have been issues with an earlier attempt)
• it could be replaced with an alternative rather than updated
• it is deprecated in favor of another dependency
• it is low-quality

Proposed solution

The obvious solution would be to support an alternative to npm which supports manifests in a format richer than strict JSON (such formats include JSON5, JSON6, and the better-known XML and YAML). The only alternative which looks serious that I see is pnpm, which supports JSON5 and YAML.

Disclaimer: I have never used pnpm, and while it is obviously better than npm on that front, I cannot even claim that pnpm is generally superior to npm.

Alternatives considered

• yapm is an npm alternative which supports YAML, but which despite its great name would apparently require lots of effort to bring to maturity.
• Insisting for npm itself to introduce support. While the original ticket was closed by an npm developer who constructively complained of “bikeshedding”, a newer and more much articulated ticket has replaced it.

[JoostK]

The goal of the Angular project is not to provide custom package management features. https://github.com/npm/rfcs/issues/291 seems to be the right place for this request (thank you for providing this context up front).

[Chealer]

Thanks @itea-dev There are obviously a number of workarounds indeed possible, some of which are mentioned in the Techiediaries article linked above and in npm issue #4482.