Step-by-step

tip

You may have heard about Yarn Plug'n'Play and be worried that your project isn't compatible yet. Don't worry!

This migration will let you keep your node_modules folder. It's only once we're done that you'll have to decide whether you want to spend time migrating to Yarn PnP. Whether you do it or stay on node_modules, migrating to Yarn Modern will have many benefits.

info

Note that those commands only need to be run once for the whole project and will automatically take effect for all your contributors as soon as they pull the branch, as long as they have Corepack enabled.

Migration steps

1. Make sure you're using Node 18+
2. Run corepack enable to activate Corepack
3. Go into your project directory
4. Run yarn set version berry
5. Convert your .npmrc and .yarnrc files into .yarnrc.yml (details here)
6. Run yarn install to migrate the lockfile
7. Commit all changes

Good, you should now have a working Yarn install! Some things might still require some adjustments in your CI scripts (for example the deprecation of arbitrary pre/post-scripts, or the renaming of --frozen-lockfile into --immutable), but at least we have a working project.

Breaking changes

Update your configuration to the new settings

Modern uses a different style of configuration files than Classic. While mostly invisible for the lockfile (because we convert them on the fly), it might cause issues if you rely on .npmrc or .yarnrc files.

• Yarn Modern now uses .yarnrc.yml. Any other file is now ignored - this includes .npmrc.
• As evidenced by the new file extension, the Yarnrc files are now to be written in YAML.

Most configuration keys have also been renamed to be more consistent. The comprehensive list of available settings can be found on the .yarnrc.yml dedicated documentation, but here are some important ones:

• Custom registries are now configured via npmRegistryServer.
• Registry authentication tokens are now configured via npmAuthToken.

Explicitly call the pre and post scripts

Some changes were made to how lifecycle scripts work in order to clarify their purpose and remove confusing behaviors. One such change is that custom pre and post scripts are no longer supported. As a result, rewrite:

{
  "scripts": {
    "prestart": "do-something",
    "start": "http-server"
  }
}

Into:

{
  "scripts": {
    "prestart": "do-something",
    "start": "yarn prestart && http-server"
  }
}

note

This only applies to user scripts, such as start & friends. It's still fine to use any of preinstall, install, and postinstall. Consult the script documentation for more information.

Use yarn dlx instead of yarn global

Yarn focuses on project management, and managing system-wide packages was deemed to be outside of our scope. As a result, yarn global got removed and needs to be replaced by yarn dlx to run one off scripts.

Don't use bundleDependencies

The bundleDependencies field (or bundledDependencies) is an artifact of the past that used to let you define a set of packages that would be stored as-is within the package archive, node_modules and all. This feature has many problems:

• It uses node_modules, which doesn't exist under Plug'n'Play installs.
• It encodes the hoisting inside the package, messing with the hoisting from other packages.

So how to replace them? There are different ways:

• If you need to patch a package, just fork it or reference it through the file: protocol (it's perfectly fine even for transitive dependencies to use this protocol). The portal: and patch: protocols are also options, although they'll only work for Yarn consumers.

• If you need to ship a package to your customers as a standalone (no dependencies), bundle it yourself using Esbuild, Webpack, Rollup, or similar tools.

Replace nohoist by nmHoistingLimits

The nohoist setting from Yarn Classic was built for React Native in order to support workspaces, but the way it worked (through glob patterns) was causing a lot of bugs and confusion, no one being really sure which patterns needed to be set. As a result, we've simplified this feature in order to only support three identified patterns.

If you were using nohoist, we recommend you remove it from your manifest configuration and instead set nmHoistingLimits in your .yarnrc.yml file:

nmHoistingLimits: workspaces

CLI changes

Renamed commands

Yarn Classic (1.x)	Yarn Modern
yarn audit	yarn npm audit
yarn create	yarn dlx create-NAME
yarn global	yarn dlx (Read more)
yarn info	yarn npm info
yarn list	yarn info -AR (--json?)
yarn login	yarn npm login
yarn logout	yarn npm logout
yarn outdated	yarn upgrade-interactive (Read more)
yarn publish	yarn npm publish
yarn upgrade	yarn up (note: updates all workspaces)
yarn install --production	yarn workspaces focus --all --production

Removed commands

Yarn Classic (1.x)	Notes
yarn check	Cache integrity is now checked on regular installs - Read more
yarn import	First import to Classic, then migrate to Yarn Modern
yarn licenses	Perfect use case for plugins - Read more
yarn versions	Use yarn --version and node -p process.versions

Not implemented yet

Those features simply haven't been implemented yet. Help welcome!

Yarn Classic (1.x)	Notes
yarn owner	Will eventually be available as yarn npm owner
yarn team	Will eventually be available as yarn npm team