Important: This documentation covers Yarn 2.
For 1.x docs, see
1 - Introduction2 - Installation3 - UsageEditor SDKsMigrationQuestions & Answers

Questions & Answers

Why should you upgrade to Yarn Modern?

While the Yarn Classic line (1.x) remains a pilar of the JavaScript ecosystem, we recommend upgrading if possible. Why that?

  1. New features: On top of the classic features you're already used to, on top of the new ones you'll discover (yarn dlx, builtin patch: protocol, ...), Modern offers plugins extending Yarn's featureset with changesets, constraints, workspaces, ...

  2. Efficiency: Modern features new install strategies, leading projects to only be a fraction of their past self; as an example, under the default configuration the stock CRA artifacts now only take 45MB instead of 237MB. Performances were improved as well, with most installs now only taking a few seconds even on extremely large projects. We even made it possible to reach zero seconds!

  3. Extensibility: The Modern architecture allows you to build your own features should you need it. No more of you being blocked waiting for us to implement this feature you dream of - you can now do it yourself, according to your own specs! Focused workspaces, production installs, project validation, ...

  4. Stability: Modern comes after years of experience with maintaining Classic; it allowed us to finally fix longstanding design issues with how some features were implemented. Workspaces are now core components, the resolution pipeline has been streamlined, data structures are more efficient... as a result, Modern is much less likely to suffer from the kind of design flaws Classic may sometimes suffer from.

  5. Future proof: A big reason why we invested in Modern was that we were coming to a situation where developing new features on Classic was becoming difficult, being too likely we would break something in the process. The Modern architecture learned from our mistakes, and was designed to allow us to build features at a much higher pace - as evidenced by the numerous new features we ship.

How easy should you expect the migration from Classic to Modern to be?

Generally, a few main things will need to be taken care of:

  1. The settings format changed. We don't read the .npmrc or .yarnrc files anymore, instead of consuming the settings from the .yarnrc.yml file.

  2. Some third-party packages don't list their dependencies properly and will need to be helped through the packageExtensions settings.

  3. Support for text editors is pretty good, but you'll need to run the one-time-setup listed in our SDK documentation.

  4. Some tools (mostly React Native and Flow) will require to downgrade to the node_modules install strategy by setting the nodeLinker setting to node-modules. TypeScript doesn't have this problem.

Most projects will only face those three problems, which can all be fixed in a good afternoon of work. For more detailed instructions, please see the detailed migration guide.

Which files should be gitignored?

If you're using Zero-Installs:


If you're not using Zero-Installs:

  • .yarn/unplugged and .yarn/build-state.yml should likely always be ignored since they typically hold machine-specific build artifacts. Ignoring them might however prevent Zero-Installs from working (to prevent this, set enableScripts to false).

  • .yarn/cache and .pnp.* may be safely ignored, but you'll need to run yarn install to regenerate them between each branch switch - which would be optional otherwise, cf Zero-Installs.

  • .yarn/plugins and .yarn/releases contain the Yarn releases used in the current repository (as defined by yarn set version). You will want to keep them versioned (this prevents potential issues if, say, two engineers use different Yarn versions with different features).

  • .yarn/sdks contains the editor SDKs generated by PnPify. Whether to keep it in your repository or not is up to you; if you don't, you'll need to follow the editor procedure again on new clones. See Editor SDKs for more details.

  • .yarn/versions is used by the version plugin to store the package release definitions. You will want to keep it within your repository.

  • .yarn/install-state.gz is an optimization file that you shouldn't have to ever commit. It simply stores the exact state of your project so that the next commands can boot without having to resolve your workspaces again.

  • yarn.lock should always be stored within your repository (even if you develop a library).

  • .yarnrc.yml (and its older counterpart, .yarnrc) are configuration files. They should always be stored in your project.

Should lockfiles be committed to the repository?


Lockfiles are meant to always be stored along with your project sources - and this regardless of whether you're writing a standalone application or a distributed library.

One persisting argument against checking-in the lockfile in the repository is about being made aware of potential problems against the latest versions of the library. People saying this argue that the lockfile being present prevents contributors from seeing such issues, as all dependencies are locked and appear fine until a consumer installs the library and uses more recent (and incompatible) dependencies.

Although tempting, this reasoning has a fatal flaw: removing the lockfile from the repository doesn't prevent this problem from happening. Contributors won't test against new versions unless they run an install, so older projects may never even notice such incompatibilities. Then, years later, users that want to work on an old project won't even be able to install it because it's latest known good state didn't get checked-in. Even without going all the way to "years later", new contributors will always have to ponder whether things broke because of their changes or because of an incompatible dependency - decreasing the number of contributions you'll receive.

Lockfiles should always be kept within the repository. Continuous integration testing is a good idea, but should be left to continuous integration systems. For example, Yarn itself runs daily tests against the latest versions of major open-source frameworks and tools. Dependabot is also a good tool that allows you to track your dependencies updates in a more integrated way.

How to share scripts between workspaces?

Little-known Yarn feature: any script with a colon in its name (build:foo) can be called from any workspace. Another little-known feature: $INIT_CWD will always point to the directory running the script. Put together, you can write scripts that can be reused this way:

  "dependencies": {
    "typescript": "^3.8.0"
  "scripts": {
    "g:tsc": "cd $INIT_CWD && tsc"

Then, from any workspace that contains its own tsconfig.json, you'll be able to call TypeScript:

  "scripts": {
    "build": "yarn g:tsc"

Is Yarn operated by Facebook?


Despite the first version of Yarn having been implemented by Sebastian McKenzie while working at Facebook, the initial design received feedbacks from various other companies (such as Tilde via Yehuda Katz) and the project was put into its own GitHub organization. Facebook kept investing in it during the following years (mostly because it proved to be a critical part of the RN ecosystem) but major contributions came from the open-source too.

Nowadays the active development team is composed exclusively of people employed by non-founders companies. Facebook employees are of course still welcome to offer contributions to the project, but they would go through the same review process as everyone else.

Why Does Facebook track us?


When Yarn got created, the npm registry used to be served through Fastly. This was apparently affecting the install performances, so the initial team decided to partner with Cloudflare and setup a reverse proxy that would simply better cache the requests before returning them. This setup didn't even have a backend on our side.

At some point npm switched to Cloudflare as well, and we turned off the proxy to replace it by a CNAME (proof). We still keep the hostname for reliability reasons - while it stands to reason that the Yarn domain name will keep being maintained for as long as Yarn is being used, the same isn't necessarily true of the npm domain name. That gives us the ability to redirect to a read-only copy of the registry should the primary source become unavailable.

While we do gather some basic client-side telemetry, no http logs can ever even reach the Yarn project infrastructure - and even less Facebook, which has no control over the project (see also, Is Yarn operated by Facebook?).

Is Yarn faster than other package managers?

Shrug 🤷‍♀️

At the time Yarn got released Yarn was effectively much faster than some of its competitors. Unfortunately, we failed to highlight that performance wasn't the main reason why we kept working on Yarn. Performances come and go, so while we were super fast it wasn't so much because we were doing something incredibly well, but rather that the competing implementations had a serious bug. When that bug got fixed, our miscommunication became more apparent as some people thought that Yarn was all about performances.

Put simply, our differences lie in our priorities. Different projects make different tradeoffs, and it's exactly what happens here. We prioritized workspaces because we felt like monorepos were providing significant value. We've spent significant resources pushing for Plug'n'Play (including through dozens of contributions to third-party projects) because we felt like this was important for the ecosystem. This is the main difference: we make our own informed decisions regarding the project roadmap.

Speed is relative and a temporary state. Processes, roadmaps and core values are what stick.