[docs] document `packageExtensions.package.peerDependenciesMeta.optional`

[nicholaschiang]

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

Describe the user story

When migrating over to Yarn v2, you'll likely be opening up a bunch of PRs in projects to add their dependency's peer dependencies to their package.json to address these errors:

➤ YN0002: │ eslint-config-airbnb-typescript@npm:8.0.2 [b17e5] doesn't provide eslint@^5.0.0 || ^6.0.0 || ^7.0.0 requested by @typescript-eslint/parser@npm:3.7.1
➤ YN0002: │ eslint-config-airbnb-typescript@npm:8.0.2 [b17e5] doesn't provide eslint@^5.16.0 || ^6.8.0 || ^7.2.0 requested by eslint-config-airbnb@npm:18.2.0
➤ YN0002: │ eslint-config-airbnb-typescript@npm:8.0.2 [b17e5] doesn't provide eslint-plugin-import@^2.21.2 requested by eslint-config-airbnb@npm:18.2.0
➤ YN0002: │ eslint-config-airbnb-typescript@npm:8.0.2 [b17e5] doesn't provide eslint-plugin-jsx-a11y@^6.3.0 requested by eslint-config-airbnb@npm:18.2.0
➤ YN0002: │ eslint-config-airbnb-typescript@npm:8.0.2 [b17e5] doesn't provide eslint-plugin-react@^7.20.0 requested by eslint-config-airbnb@npm:18.2.0
➤ YN0002: │ eslint-config-airbnb-typescript@npm:8.0.2 [b17e5] doesn't provide eslint-plugin-react-hooks@^4 || ^3 || ^2.3.0 || ^1.7.0 requested by eslint-config-airbnb@npm:18.2.0
➤ YN0002: │ eslint-config-airbnb-typescript@npm:8.0.2 [b17e5] doesn't provide eslint@^5.16.0 || ^6.8.0 || ^7.2.0 requested by eslint-config-airbnb-base@npm:14.2.0
➤ YN0002: │ eslint-config-airbnb-typescript@npm:8.0.2 [b17e5] doesn't provide eslint-plugin-import@^2.21.2 requested by eslint-config-airbnb-base@npm:14.2.0

I've already created two such PRs (this one which fixes the errors above and this one for Next.js's use of sass-loader) and have only been working on migrating to Yarn v2 for about 30 mins haha.

Describe the solution you'd like

One should be able to specify optional peer dependencies in the .yarnrc.yml file under the packageExtensions key like so:

packageExtensions:
  next@9.5.x:
    peerDependencies:
      sass: "^1.3.0"
      node-sass: "^4.0.0"
      fibers: ">= 3.1.0"
    peerDependenciesMeta:
      node-sass:
        optional: true
      fibers:
        optional: true

This follows the same specs implemented here.

Describe the drawbacks of your solution

This section is important not only to identify future issues, but also to see whether you thought your request through. When filling it, ask yourself "how can I break it".

There is a much more concise way to specify the same thing (but it doesn't follow the current package.json syntax, which is why I think it should be avoided for now):

packageExtensions:
  next@9.5.x:
    peerDependencies:
      sass: "^1.3.0"
    optionalPeerDependencies:
      node-sass: "^4.0.0"
      fibers: ">= 3.1.0"

[bgotink]

It's actually already possible to specify optional peer dependencies in the package extensions, e.g.

berry/.yarnrc.yml

Lines 76 to 83 in b94bcf9

	typedoc@*:
	peerDependenciesMeta:
	"@strictsoftware/typedoc-plugin-monorepo":
	optional: true
	typedoc-neo-theme:
	optional: true
	typedoc-plugin-yarn:
	optional: true

The example configuration you've given should work as well. Could you try it out?

I did notice the documentation only shows peerDependencies and dependencies. That could be improved, as both dependenciesMeta and peerDependenciesMeta are also supported.

[nicholaschiang]

@bgotlink yeah, it looks like those work.

Could you update the docs then?

[Venryx]

@nicholaschiang Do you mean something like this?: https://yarnpkg.com/configuration/manifest#peerDependenciesMeta

[merceyz]

I'll reopen this so we don't forget to document it

@nicholaschiang Do you mean something like this?: https://yarnpkg.com/configuration/manifest#peerDependenciesMeta

That's not the same thing, this issue was about packageExtensions.<package>.peerDependenciesMeta in .yarnrc.yml not peerDependenciesMeta in package.json