docs: clarify what peerDependenciesMeta does

[xuhdev]

No description provided.

[wraithgar]

The whole section needs to be removed if it does not apply to the currently supported version of npm. We don't need to document old unsupported versions.

[xuhdev]

@wraithgar Got it, I've updated the PR. peerDependenciesMeta is still used by the latest npm, but the current doc seems to have missed the most important points while talks a lot about the behavior of old npm versions.

[wraithgar]

Npm would not automatically install optional peer dependencies.

This is a very confusing and potentially misleading sentence. At a glance it reads that npm does not install optional peer dependencies. In fact it does, it just does not raise an error if they can not be installed.

[xuhdev]

I tried this myself, npm seems to not install optional peer dependencies by default. I"m on npm version 10.7.0.

1. mkdir my-package && cd my-package
2. Save the following file to package.json:

{
  "name": "tea-latte",
  "version": "1.3.5",
  "peerDependencies": {
    "lodash": "4.17.21",
    "core-js": "3.37.0"
  },
  "peerDependenciesMeta": {
    "lodash": {
      "optional": true
    }
  }
}

3. npm install.

Observe that node_module doesn't contain lodash, but it contains core-js.

Then:

1. npm pack (which generates tea-latte-1.3.5.tgz)
2. mkdir ../user && cd ../user
3. npm install ../my-package/tea-latte-1.3.5.tgz

Same effect, only core-js is installed, not lodash.

[wraithgar]

Well then my memory of the situation was wrong. I must have gotten optional and optional peer dependencies confused. Thanks.

[wraithgar]

Small grammar suggestion and we can land this.