Cli: [FEATURE] Document the peerDependenciesMeta in the package.json

[abdonrd]

I cant find info about the peerDependenciesMeta field in the package.json:

https://docs.npmjs.com/files/package.json

References

It was mentioned at the npm blog here:

https://blog.npmjs.org/post/186983646370/npm-cli-roadmap-summer-2019

New features likely to land on the 6.x branch:

Add support for the peerDependenciesMeta field. (#224)

Also here in the changelog:

https://github.com/npm/cli/releases/tag/v6.11.0

Also the release announcement:

https://npm.community/t/release-6-11-0/9572

[abdonrd]

Any news? Thanks in advance!

[jrylan]

Formal documentation on this feature would be great. I know npm 7+ is going back to the behavior of installing peerDependencies for you if they are not already in your package.json. Now I'm left wondering how that works when a peer dependency is marked as optional in peerDependenciesMeta.

Edit: I've confirmed locally that peerDependencies marked as optional using peerDependenciesMeta are auto-installed.
I've opened this issue at npm/rfcs: https://github.com/npm/rfcs/issues/221

[abdonrd]

Any news?

[jrylan]

@abdonrd there is a PR here that is not yet merged: https://github.com/npm/cli/pull/1822

[wheresrhys]

Is peerDependenciesMeta deprecated in favour of optionalDependencies?

[ljharb]

@wheresrhys they're entirely different, albeit similar. optionalDependencies means, if the dep fails to install, don't fail the overarching install. peerDependenciesMeta allows you to provide extra information about peer deps, and marking one "optional" means "it's not an error if it's missing".

[wheresrhys]

Thanks. I had to read that through a few times to grasp it, but I think I've got it now.

This distinction really needs documenting properly. I've just had a PR submitted https://github.com/wheresrhys/fetch-mock-jest/pull/22 where the submitter almost certainly wants peerDependenciesMeta but has used optionalDependencies.

I'd be happy to help, but maybe best as a non-expert reviewer as I don't think I have the familiarity needed to actually write the docs