yarnpkg berry: a package manager that installs and patches itself

The repository installs Yarn with Yarn, and you can read that in the tree

The clearest statement of how this project works is its own directory listing. At the top level sit two plug-and-play runtime files, the loader and the generated state, which are committed rather than generated on your machine, and that is the signature of a project consuming its own installation mode. The manifest declares itself private, scoped to the monorepo, with a workspace glob over the packages directory, and six of its nineteen development dependencies point at those workspaces rather than at a registry.

"@yarnpkg/core": "workspace:^"
"typescript": "catalog:"

So the CLI, the core library, the filesystem helper, the archive library and the generated SDKs are all built from this tree and installed by the tool being developed. There is also a project configuration file, a plugins manifest, a constraints file, and both the old configuration file and the current one sitting side by side, which is a small fossil record of the version change.

The resolutions table is a list of patches the project applies to itself

The most instructive part of the manifest is its resolutions table, because it shows the mechanism the project expects users to reach for. One entry redirects a range of a terminal rendering library to a patch file stored under the project's own patch directory, whose file name carries a hash. Another points a layout library at a patch file inside the repository. Two ranges of an HTTP fetch library are redirected to a portal, which is the mechanism for substituting a package with a local copy, and the copy in question has a name that says exactly what it is: a smaller one. A fourth entry pins a network library to an older release and patches it. Alongside that, four packages are marked as not needing a build step. None of this is exotic, but it is a lot of machinery, and it is the price of running a bleeding edge toolchain on itself.

A portable shell is what makes one script work on three systems

Of the architectural claims in the readme, the one with the most immediate effect on your repository is the shell. Rather than asking projects to keep a separate script per operating system, the tool provides a bash-like portable shell and runs package scripts through it, so the same script behaves the same way on Windows, on Linux and on macOS. The shell is a package in this repository rather than a re-export, which is consistent with the project's claim that it is written in TypeScript and fully type checked, and with the claim that it is first and foremost a programmatic API rather than only a command line. The readme is also careful about scope: it says the tool supports Node by default but is not limited to it, and that plugins are how support for other languages is added.

Plugins are added by putting a file in your repository

The extension model heads the list of things the readme says its novel architecture allows, and its simplicity is the point. Adding a plugin is described as being as simple as adding it into your repository, which means the extension boundary is a file in your project rather than a fork or a patch to the tool. Two things follow from that. The first is that a plugin is code you add to your own repository, which is what makes it worth reviewing. The second is that language support is a plugin problem, not a rewrite, which is why the readme pairs the plugin system with the claim about other languages. In this repository the machinery for working on plugins is visible as a plugins manifest and two build scripts that generate mock plugins, one for the constraints system and one for the command execution path.

It runs the newest of every community toolchain, daily

There is a status section that explains the testing policy, and it is worth reading for anyone who upgrades a package manager. On top of the classic integration tests, the project runs Yarn every day against the latest versions of the toolchains its community uses, with the comment that this is just in case, and that everything should be green. The badge list below it is generated by running a script, and it names end-to-end workflows for projects built with view frameworks, documentation tools, bundlers, linters, test runners, formatters, compilers and component libraries, including a handful of runs against the non-plug-and-play installation mode. The consequence for you is direct: a new Yarn release can change how someone else's project builds, even though nothing in your code changed, which is an argument for pinning and reading the changelog.

Two sponsors are credited with changing what the tool does

The readme lists sponsors with unusually specific claims, and two of them are about engineering rather than money at the end of the quarter. One company is credited with sponsoring a maintainer's time for more than a year, and with upgrading the project's own telemetry plan on top of that. Another is credited with sponsoring time from very early in the two series of development, with the specific consequence named: their investment is the reason that Yarn two supports the traditional installation mode better than it used to. Two more are credited as historical infrastructure partners for the project website, one of which is noted as no longer mirroring the package registry directly while still serving the site. A documentation search provider is credited with powering search on both versions of the documentation. Reading the list tells you which parts of the roadmap are actually funded.

Everything you need to read is one domain away

The last thing to notice is how little this repository explains on its own. The installation section is a link to a guide on the project site. The migration section is a link to a migration guide on the same site. Documentation and API reference are both links, with the API pointed at a separate path on that site. So the repository is a development trunk and a release vehicle, not a manual, and a reader who clones it expecting to find out how to install anything will find four links instead. What is local is the project's own governance and history: a governance file, a code of conduct, a codeowners file, a security policy, a history document, a changelog, and a tips file. Release tags are named after the command line package rather than after the repository, which is another small reminder that you are looking at one package inside a larger distribution.

Editorial conclusion

It suits a team that wants workspaces and a cross-platform script shell without leaving the JavaScript ecosystem, and that is prepared to read a manifest with patch directives in it. It does not suit someone who wants the install steps written down in the repository, because every one of them is a link to a site, and it does not suit a team that treats a package manager upgrade as a no-op, since the project tests daily against the newest toolchains, just in case, as the readme puts it. Check four things before you commit: whether the plugins you would need exist, because that is where the real extension points are, whether you accept a native installer path for one project that differs from another, what your scripts assume about the shell, and which release line you will pin.

Frequently asked questions

Official sources

1. License: BSD-2-Clause
2. Project website
3. README
4. Releases
5. yarnpkg/berry on GitHub