Yarn Berry: the package manager that ships as a plugin host

The problem Yarn Berry is built around

Yarn Berry is not a rewrite of the classic Yarn CLI. It is a package manager split into separate packages, with @yarnpkg/core as the Node API and @yarnpkg/cli as the command line front end. The README frames the architecture as enabling things it says are impossible with existing solutions: plugins added by dropping them into your repository, support for languages other than Node through those plugins, native workspaces that the CLI itself uses, and a bash-like portable shell so package scripts behave the same on Windows, Linux and macOS.

The audience follows from that. If you maintain a repository where several packages are versioned together, where installs must be reproducible across operating systems, or where you want to call the resolver from your own script instead of shelling out, the split-package design is the point. If you just want an npm-compatible install in a single-package project, most of that architecture is overhead you will never touch.

Plugins, workspaces and the portable shell

The mechanism is plugin registration rather than a monolithic binary. The README states that adding a plugin is as simple as adding it into your repository, and that plugins can add support for languages beyond Node. In practice that means the resolver, the fetchers and the linkers are contributions to a core, and the CLI only exposes them.

Workspaces are handled natively, and the README notes the CLI takes advantage of that, which is why cross-workspace commands do not need a separate tool. The portable shell is a separate package, yarnpkg-shell, described as bash-like and used to make package scripts portable across the three major desktop platforms. That is a real behavioural difference from running scripts through the host shell: the shell is shipped with Yarn, so a script that works on a developer's machine is not depending on cmd.exe or zsh.

The repository layout confirms the split. The top level holds .pnp.cjs and .pnp.loader.mjs alongside .yarnrc.yml, and packages/ holds the individual packages. The monorepo's own package.json declares workspaces as packages/* and depends on @yarnpkg/cli, @yarnpkg/core, @yarnpkg/fslib, @yarnpkg/libzip and @yarnpkg/sdks as workspace references. The project consumes itself, which is the clearest signal that the workspace model is meant for real monorepos and not a demo feature.

Installing Yarn Berry and running a first install

The README does not inline installation steps. It points to the Installation Guide at yarnpkg.com/getting-started/install and a separate Migration Guide at yarnpkg.com/getting-started/migration, so the exact command depends on the guide rather than the repository text. What the repository does show is the shape of a configured project: a .yarnrc.yml at the root and a .yarn/ directory next to it.

A first use starts with enabling the package manager through Corepack, which is how Node ships Yarn. The command below makes the Yarn version available on your PATH; the guide is the authority on the exact version pin.

corepack enable

Then set the version you want the project to use and install. The repository's own yarn.config.cjs and .yarnrc.yml show that configuration lives in YAML, so edits go there rather than into a package.json field.

yarn set version stable
yarn install

After the install completes you should see a lockfile and a .yarn/ directory in the project root. If you keep the default install mode, node_modules appears as well; if you switch to Plug'n'Play, the top-level .pnp.cjs and .pnp.loader.mjs files are what the runtime loads instead.

Where Yarn Berry is the wrong tool

The design assumes Node as the primary ecosystem. The README is explicit that Yarn supports Node by default but is not limited to it, with other languages arriving through plugins. That is a conditional, not a guarantee: if you need first-class support for a non-Node ecosystem today, you are either writing the plugin or waiting for someone else to.

The second constraint is the install mode. Yarn Berry can install into node_modules, and the README credits SysGears sponsorship for the fact that Yarn 2 supports node_modules installs better than it used to. But the repository's own root carries .pnp.cjs and .pnp.loader.mjs, which means the project itself runs on Plug'n'Play. Tools that read node_modules directly, or that assume a flat directory of packages on disk, will not see anything under Plug'n'Play. That is a compatibility question you have to answer per tool, not a setting that makes the problem disappear.

Third, the documentation is deliberately thin in the repository. The README defers installation, migration and API questions to yarnpkg.com. If you are evaluating offline or in an environment where you cannot reach the website, the repository alone will not tell you how to migrate.

npm and pnpm as the alternatives

npm is the baseline that ships with Node and needs no separate install step. Its model is a node_modules tree produced by the bundled CLI, with no plugin system and no programmatic core exposed as a supported API. The difference is architectural: npm is one tool you run, Yarn Berry is a core library plus a CLI plus whatever plugins the project registers. If your team never writes a plugin and never calls the API, npm gives you the same install outcome with fewer moving parts.

pnpm takes a different route again, using a content-addressable store and symlinked node_modules rather than Plug'n'Play or a plain tree. That keeps the node_modules interface that tools expect while deduplicating across projects on the same machine. Yarn Berry's Plug'n'Play instead removes node_modules and resolves through a generated .pnp.cjs file. The trade-off is symmetric: pnpm keeps compatibility with tools that expect a directory, Yarn Berry removes the directory and asks those tools to adapt.

Maintenance, upgrades and the licence

The repository is not archived, and the last push was on 2026-09-19. Recent releases are on a steady cadence: @yarnpkg/cli 4.18.0 on 2026-07-29, 4.17.1 on 2026-07-08 and 4.17.0 on 2026-06-15. The README also describes a daily end-to-end run against the latest versions of community toolchains, generated into a status list by a script in the repository, which is a maintenance signal that goes beyond the release tags.

The upgrade cost sits in the major version boundary. Yarn 1 (classic) and Yarn Berry are different tools with a migration guide between them, so a jump from classic is a project, not a version bump. Within the 4.x line the releases above are patch and minor versions, which is the cheaper path. The repository includes a CHANGELOG.md and a HISTORY.md at the top level, so release notes are tracked in-tree.

The licence is BSD-2-Clause, declared in both the repository metadata and the monorepo package.json. That is a permissive licence, which generally means you can use and redistribute the code with the licence text retained; it says nothing about the packages you install with the tool, which carry their own licences. This is a description of what the repository states, not legal advice, and your own counsel should review anything you redistribute.

Editorial conclusion

Adopt Yarn Berry if you run a JavaScript or TypeScript monorepo and want workspaces, a portable shell for package scripts, and a Node API you can script against. Do not adopt it if you need a package manager that also handles non-Node ecosystems without writing plugins, or if your build tooling assumes a plain node_modules tree you cannot change. Verify first that your CI image has Corepack enabled, that your lockfile is committed, and that the install mode you pick (node_modules or Plug'n'Play) is supported by every tool in your build chain.

Frequently asked questions

Official sources

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