Migrating to Yarn 2
Last updated 16 July 2020
To our excitement, Yarn 2 was released in early 2020. The team has created a “zero downloads” package manager, which means users may use “vendor” directories to include their yarn binaries, dependencies, and development dependencies in their repositories. Learn more about Yarn’s new philosophy.
This article is intended to help current Heroku users migrate from Yarn 1 to Yarn 2. Apps being migrated should already be using Yarn 1 and are using the most up-to-date version of the Heroku Node.js buildpack. This article will not work for applications that install Yarn from other scripts, such as the Heroku Ruby buildpack. Heroku expects all dependencies to be included in the
.yarn directory to take full advantage of “zero downloads”.
Heroku users using Yarn are not required to migrate to Yarn 2, and users will have access to Yarn 1 in their apps after it is deprecated. However, it’s advised to migrate to Yarn 2 to ensure the most up-to-date bug fixes and security patches in the package manager.
Use this article to migrate your app code locally to Yarn 2, as well your application on Heroku.
The following will reference checking files into
git while directions could also be applied to other version control systems.
Prepare local environment
Enter the directory of the source code that needs the migration. The local commands will be run at the root of the project. Make sure the local yarn version is up to date. To update it locally, run install with npm:
npm install -g yarn
The version should be
>= 1.22.4. Run
yarn -v to confirm.
Move custom cache directories to workspaces
package.json, change your
workspaces. For example, if you have the following:
"cacheDirectories": [ "client/node_modules" ]
Change it to the following, and specify that the project is private:
"workspaces": [ "client" ], "private": true,
There’s no need to specify the
node_modules directory. Make sure the
"name" key in the
package.json of the subdirectory reflects the directory name and the workspace name specified in the root
Next, delete any
node_modules folders and
yarn.lock files in subdirectories, and go to your application directory and run
cd ~/path/to/project && yarn install
This should update the
yarn.lock file of your directory to reflect the entire dependency tree specified by the workspaces. Confirm that the lock file has been updated by looking for a dependency that has been specified in a
package.json of a subdirectory.
Make changes to source code
There are additional files that must be checked into git in order to use Yarn 2 on Heroku. Yarn subscribes to a “zero-download” philosophy. There will be additional costs associated with adding more files and directories to be check in, but this will create faster builds on Heroku.
yarn to set the yarn version on the source code.
yarn set version berry
This will create a
.yarnrc.yml file and a
.yarn directory. Check both into git and make sure they are available to Heroku at build time. In the
.yarn directory, there is a
releases directory that contains a
Next, install the dependencies from the
yarn.lock file will be modified. Check this in these changes into git.
pnp.js file is also generated - this is the “Plug N Play” file. Yarn uses it to access the packages. There are also additional files that are generated in the
.yarn directory, including a new directory
cache where dependencies are installed, and
install-state.gz files. Check the contents of
.yarn into git.
The contents of
.yarn/cache are not comparable to
node_modules. The files are compressed and are meant to be checked into the project.
Update Heroku environment
Clear App cache
Since Heroku won’t be restoring the cache at the beginning of the build or storing it at the end of the build, you can go ahead and purge any cache that is leftover from previous builds.
Make sure you have
heroku-cli installed. Then, install the
heroku plugins:install heroku-repo
Next, run the command to clear the cache.
heroku repo:purge_cache --app $APP_NAME
After this, you’ll want to redeploy your app, but first finish up the next steps to ensure a successful deploy.
Change environment variables
Right now, Heroku doesn’t support installing dependencies with Yarn 2 since it makes the assumption that the user will be using the
.yarn directory to use zipped up modules that are used with the
pnp.js file. This is temporary, and Heroku will eventually be able to install the modules and cache them. If you plan on installing dependencies during the build, then feel free to leave the following environment variables as they are. You will see warnings, but your build will not fail.
It’s time to remove the environment variables that are associated with Yarn 1 and
First, remove the
NODE_MODULES_CACHE environment variable. Since Yarn 2 uses the
.yarn directory to vendor dependencies, this variable can be set to false.
heroku config:set NODE_MODULES_CACHE=false
Since all dependencies end up in the vendor directory, the environment variable that tells Heroku to include or not include
devDependencies can be unset:
heroku config:unset NPM_CONFIG_PRODUCTION YARN_PRODUCTION
If you’ve set any tokens for accessing a private registry, feel free to unset those as well. You may do something like this:
heroku config:unset PRIVATE_NPM_TOKEN
Test your App
After you’ve made your changes, make sure to run your test suite on your app’s code. Once the tests have passed successfully, deploy your application to Heroku. Confirm that the build has been successful.
If you run into any issues, please open an Issue on GitHub.