What’s new in new Yarn major version

Yarn was developed as an alternative way to handle Node.js dependencies to NPM but was fully compatible with it. They were both manipulating the node_modules directory and switching to one or the other tool was straightforward.

Yarn 2 and Yarn 3 have evolved to use another approach, aiming at making dependency management for Node.js application more efficient, especially during its deployment.

You are not forced to migrate to Yarn 2 or 3, compatibility with Yarn 1 will be kept as long as possible. But to enjoy fastest deployments and last patches, you are encouraged to upgrade your project or get back to NPM.

New versions of Yarn have 2 ways to work:

• With Plug’n Play: it is expected to checkout the application dependencies .yarn/cache in your git repository. It will accelerate deployment since it won’t be necessary to download dependencies that are already in your repository. Don’t worry Yarn is optimizing and compressing them to prevent using too much space. No node_modules directory will be present at the end of the build.

• Without Plug’n Play: Dependencies will be downloaded normally during the deployment and linked into the node_modules directory, it’s retrocompatible with most tools you have been using.

More details in the Yarn official documentation.

Setting up your project

1. Switch to the last stable Yarn version

Configure Yarn to use its more recent ≥ v2.0.0 release

yarn set version berry
yarn install

The file yarn.lock is updated and new files are added to the .yarn directory.

2a. Configure with Plug’n Play enabeld

Update your .gitignore file

Modify your .gitignore to ensure only required files are committed into your repository, add the following:

.yarn/*
!.yarn/cache
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions

Disable dependency caching in your app

scalingo --app my-app env-set NODE_MODULES_CACHE=false

Add checkout config, metadata and cache files

git add yarn.lock .yarn .pnp.*
git commit -m "Deploy with Yarn 3 with Plug'n Play mode"

2b. OR - Configure without Plug’n Play enabled (retrocompatibily mode)

Update your .gitignore file

Modify your .gitignore to ensure only required files are committed into your repository, add the following:

.pnp.*
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions
node_modules

Update your .yarnrc.yaml file

Modify or add the line:

nodeLinker: "node-modules"

Add checkout config, metadata files

git add yarn.lock .yarn
git commit -m "Deploy with Yarn 3 without Plug'n Play mode"

3. Reset your deployment cache

Since it may create conflict with the new dependencies management system.

scalingo --app my-app deployment-delete-cache

4. Deploy your application

git push scalingo master