Yarn Modern with Plug'n'Play and "Zero-Installs"
Ever since Facebook released Yarn in 2016, it has become an essential tool for developers. According to Stack Overflow’s 2022 survey of 70,000 developers, 27% of those respondents use Yarn. Introducing a lock file and parallel downloads, Yarn pushed the envelope of what a JavaScript dependency management tool can do. The release of version 2 (known as Yarn Modern or Yarn Berry) introduced Plug’n’Play with Zero-Installs. In this article I will walk you through creating a project using the Yarn Modern, adding Plug’n’Play and Zero-Installs as we go.
What is Plug’n’Play and Zero-Installs?
Plug’n’Play is a strategy for installing a project’s dependencies. Zero-Installs is a collection of Yarn’s features used to make your project as fast and stable as possible.
Have you ran into a problem with a project’s dependencies that was
only solved with rm -rf node_modules? Or running a node script
on your machine works but that same script fails to run on a
coworker’s? The Yarn docs calls this the “node_modules
problem”.
The “node_modules problem” refers to the inefficiencies caused by
using the Node Resolution
Algorithm to
look up a project’s dependencies. The Node Resolution Algorithm
looks for files that are require’d or import’d, recursively
(and indiscriminately) searching all the way to the home directory
of the computer it is being run on. With the volume of files
installed, and different stat and readdir calls, this
traditional approach is costly in space and time. Every minute
spent on CI / CD installing node modules and bootstrapping your
application is money coming out of someone’s pocket.
Plug’n’Play and Zero-Installs provide a solution: replace large
node_modules downloads with zipped cached files that unzip at
runtime.
Setting up a new project with Yarn Modern
First, we need to upgrade to the latest version of Yarn.
npm i yarn -g
We are going to create a new folder and set up a git repo using Yarn inside of it.
mkdir yarn-modern
cd yarn-modern
git init
yarn init -y
Running ls -l should show us the following files:
.editorconfig
.gitignore
README.md
package.json
yarn.lock
We need to set up our project to install our dependencies in the
node_modules folder. We can do that by running yarn config set nodeLinker: node-modules from the terminal. That shows us the
following output:
➤ YN0000: Successfully set nodeLinker to 'node-modules'
Running that command creates a .yarnrc.yml file with the
following contents:
nodeLinker: node-modules
We want to commit these files. Doing so will allow us to run git status to see subsequent changes in isolation. Before doing that,
we need to make a change to .gitignore.
Let’s look at the contents of .gitignore first:
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions
# Swap the comments on the following lines if you don't wish to
use Zero-Installs
# Documentation here: https://yarnpkg.com/features/Zero-Installs
!.yarn/cache
#.pnp.*
There are a number of .yarn folders that we do not want to
ignore. They can serve a purpose but they are beyond the scope of
this article. Looking at the bottom section, there is the
following comment:
# Swap the comments on the following lines if you don't wish to
# use Zero-Installs
By following those instructions we will turn off Zero-Installs,
which was set up for us when we ran yarn init -y. Turning it off
now will help us better understand how Zero-Installs works when we
enable it.
Update the bottom of the .gitignore to this:
#!.yarn/cache
.pnp.*
Add node_modules to .gitignore as well.
When that is done, commit the changes.
Let’s add lodash as a dependency.
yarn add lodash
Running git status we should see a familiar sight:
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working
directory)
modified: package.json
modified: yarn.lock
Running ls -l, we see a node_modules folder. We also have a
.yarn folder. The .yarn folder has a cache folder along with
a install-state.gz folder. We won’t be covering what
install-state.gz does but you can find out more about the files
and folders that can end up in your .yarn folder
here.
.yarn/cache holds a local, cached copy of our project
dependencies.
ls -ls .yarn/cache will show us something like this:
lodash-npm-4.17.21-6382451519-eb835a2e51.zip
If we were to delete node_modules and re-run yarn install, it
would load it from .yarn/cache instead of fetching it from the
remote repository. That is a nice touch.
Next we will create a small file in our project’s root that loads
lodash, index.js.
const _ = require("lodash");
console.log(_.camelCase("FOO_BAR_BAZ"));
Running node index.js we get the following:
fooBarBaz
As expected, we are loading lodash from node_modules. Commit
this change. Next we are going to enable Plug’n’Play.
Adding Plug’n’Play
To add Plug’n’Play, we need to change the nodeLinker config
value. Run the following command in your terminal:
yarn config set nodeLinker pnp
Done successfully, that will output the following:
➤ YN0000: Successfully set nodeLinker to 'pnp'
You can also change this setting manually by opening
.yarnrc.yml and changing nodeLinker to pnp:
nodeLinker: pnp
Run yarn install. You should see the following line somewhere in
the output:
➤ YN0031: │ One or more node_modules have been detected and will
be removed. This operation may take some time.
Running ls -l should show that there is no longer a
node_modules directory. Lets make sure our index.js file is
still working:
node index.js
Uh oh! We got an error, that looks something like this:
node:internal/modules/cjs/loader:942
throw err;
^
Error: Cannot find module 'lodash'
Require Stack:
...
Using Plug’n’Play requires using the yarn binary, like so:
yarn node index.js
It works! Running yarn node index.js, we can see console.log
from our index.js file. Instead of node_modules, our
dependencies are loading from .yarn/cache instead.
Zero-Installs
To achieve zero-install state with Plug’n’Play, we need make an
update to .gitignore, replacing its contents with the following:
.yarn/*
!.yarn/cache
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions
Running git status, you see the previously ignored Yarn cache
files along with a .pnp.cjs showing up as untracked files. We
will commit these files to the repo. This how we achieve
Zero-Installs, by adding our .yarn/cache files to the repo along
with the .pnp.cjs file. Yarn’s website has a good description
of what the .pnp.cjs file is used
for:
The .pnp.cjs file contains various maps: one linking package names and versions to their location on the disk and another one linking package names and versions to their list of dependencies. With these lookup tables, Yarn can instantly tell Node where to find any package it needs to access, as long as they are part of the dependency tree, and as long as this file is loaded within your environment.
Adding your dependencies to your repo may feel strange at first but you quickly get used to it.
If you are adding Plug’n’Play to a new project, you may run into
some challenges. Plug’n’Play is more strict compared to other
JavaScript package managers. This is by design. 3rd party packages
may not have listed their dependencies in a manner that works with
the strict nature of Plug’n’Play. This is either a feature or bug
of how other package managers work. It all depends on how you look
at it. Yarn Modern provides tools to tackle these challenges:
yarn patch, yarn patch-commit, and packageDependencies.
There is also some additional work needed to get your IDE to work
with
Plug’n’Play.
I will cover these topics in a future post.
Yarn with Plug’n’Play and Zero-Installs is an exciting addition to
the package manager landscape. Skipping the need to install node
modules on every build results in faster deployments. Getting the
latest dependencies is as simple as running git pull. While it
may seem unconventional at first, once adopted, it can increase a
team’s overall productivity.