Clarify third party plugins distribution model and usage of builder / `yarn plugin import`

Plugins are one of the best features introduced to berry. It remains however a bit unclear in the current documentation and in the current behavior of yarnpkg-builder how this feature fits into the larger ecosystem (i.e. outside the internal use of plugins by berry itself).

• builder build plugin always normalizes the plugin name to ‘@yarnpkg/xxxxx’. It’s not clear today if this is intended or if there is something more that we need to know,
• the tutorial for plugin development does not use the yarn plugin command line, which behaves slightly differently from the tutorial example. Here again we may need a bit more clarity on the best practice of how plugins get added to a berry project,
• yarn plugin import has different treatment depending on whether the plugin is hosted on yarnpkg repo or not. If not, it has to be a downloadable single file bundle. Why we can’t just ship third-party plugins as npm modules, add them as dev deps, and then yarn can just import from there, like usual?
• even when a plugin is imported from the local filesystem, yarn plugin import builds a different cjs file. Not clear how is that working with builder and if we (as plugin developers) need to know about it.

[arcanis]

The first issue is how to distribute the plugin to the users. People just do git clone and yarn install and expect everything to be ready. Now we will expect them to do another step as well: yarn plugin import https://xxxxx/plugin.js.

Note that plugins are meant to be checked-in (same as the Yarn binary itself), so cloning is all that’s required to have a working environment.

[arcanis]

is the intention for yarn plugins only to be those that strictly interact with the @yarnpkg/* ecosystem and a select set of modules exposed by the require function that factory exposes?

Yes and no - plugins can’t access third-party packages out of the box because it would mean that they wouldn’t be able to execute until after the project has been installed (and thus after the plugins have already been executed).

That being said, you can bundle your plugin sources into a single binary (like we do for Yarn), in which case you can use whatever third-party you want since they’ll be stored inside the plugin anyway. This is what @yarnpkg/builder does for you, although it’s not well enough documented at the moment.