An introduction to Yarn

Yarn is a package manager for JavaScript projects.

It reads dependencies and scripts from package.json, installs packages from registries such as npm, and records exact resolutions in yarn.lock.

Modern Yarn is significantly different from Yarn Classic. If an existing project contains a yarn.lock file and Yarn configuration, use the Yarn version declared by that project instead of silently upgrading it.

Install Yarn with Corepack

Yarn recommends Corepack because it lets each project declare its package manager version.

Install Corepack, then enable its command shims:

npm install -g corepack
corepack enable

Some Node.js distributions already include Corepack, while others do not. The command above follows Yarn’s current installation guide.

Do not install modern Yarn globally with npm install -g yarn. A global Yarn version can change independently of your project and make installs less reproducible.

Start a project

Initialize a new project with modern Yarn:

yarn init -2

In an existing project, pin the current stable Yarn release:

yarn set version stable
yarn install

The project records the package manager it expects. Commit the resulting package.json, yarn.lock, .yarnrc.yml, and any other Yarn-managed project files required by your configuration.

Run:

yarn --version

to see the active version.

Install project dependencies

When you clone a project, install everything declared in package.json:

yarn install

Yarn updates or creates yarn.lock. Commit that lockfile so the team and CI resolve the same dependency tree.

In CI, prefer an immutable install:

yarn install --immutable

This fails if Yarn would need to modify the lockfile.

Add dependencies

Add a runtime dependency:

yarn add lodash

Add a development dependency:

yarn add --dev vitest

Add a peer dependency:

yarn add --peer react

You can request an exact version or range:

yarn add lodash@^4

Check the official yarn add reference for supported protocols and flags.

Before adding an unfamiliar package, review its repository, maintenance history, dependencies, and install scripts. A package runs with your user’s permissions when your tools execute it.

Remove dependencies

Remove a package from the current workspace:

yarn remove lodash

Yarn updates both package.json and yarn.lock.

Update dependencies

Upgrade one dependency across the project:

yarn up lodash

Upgrade matching dependencies interactively:

yarn up --interactive

Modern Yarn uses yarn up; old tutorials may show the Yarn Classic yarn upgrade command.

To update the Yarn release used by the project:

yarn set version stable
yarn install

Review dependency changes and run the project’s tests before committing an update.

Run scripts and package binaries

Given this package.json:

{
  "scripts": {
    "dev": "vite",
    "test": "vitest run"
  }
}

run the scripts with:

yarn dev
yarn test

yarn run test is the explicit form.

To run a package once in a temporary environment, use yarn dlx:

yarn dlx create-vite

Use dlx for one-off commands, not as a replacement for a recorded project dependency. Yarn’s dlx documentation explains why temporary commands are not reproducible installs.

Understand why a package is installed

Use:

yarn why PACKAGE

This shows which workspace or dependency brought the package into the project.

Run the npm registry vulnerability audit with:

yarn npm audit

An audit report needs judgment: verify whether the vulnerable code is reachable and whether an upgrade introduces breaking changes.

Plug’n’Play and node_modules

Modern Yarn uses Plug’n’Play by default. Instead of creating a traditional node_modules tree, it records dependency locations in a loader file.

If a tool does not work with Plug’n’Play, configure the familiar node_modules strategy in .yarnrc.yml:

nodeLinker: node-modules

Then run:

yarn install

Yarn also supports a pnpm-style linker. The install modes documentation explains the tradeoffs, and the Plug’n’Play guide covers compatibility.

Workspaces

Workspaces let one repository contain multiple related packages with one install and one lockfile.

They are useful for monorepos and for applications that share internal packages. Yarn can run commands across workspaces and use the workspace: protocol to link them together.

See the Yarn workspaces guide when a single-package project starts to grow.

Related posts about devtool: