Yarn Package Manager

Yarn cheatsheet — fast JavaScript package manager. yarn install, yarn add package, yarn remove, yarn run script, yarn upgrade. Workspaces and PnP support covered.

7 min read

What it is

Yarn is a fast, reliable, and secure JavaScript package manager for managing your project’s dependencies. You reach for Yarn when you need to install, update, or remove packages for your Node.js projects.

Installation

Linux (Debian/Ubuntu):

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update && sudo apt install yarn

Linux (Fedora/CentOS/RHEL):

curl -sL https://rpm.nodesource.com/setup_16.x | sudo bash -
sudo yum install yarn # or dnf install yarn

macOS: Using Homebrew:

brew install yarn

Windows: Download the installer from the official Yarn website: https://classic.yarnpkg.com/en/docs/install

Core Concepts

package.json: The manifest file for your project. It describes your project, lists its dependencies, and includes scripts. Yarn reads and writes to this file.
yarn.lock: A file generated by Yarn that locks down the exact versions of every package and sub-dependency that were installed. This ensures reproducible builds across different environments. Do not edit this file manually.
Dependencies: Packages that your project needs to run. These are listed in package.json under dependencies (for production) and devDependencies (for development).
Registry: By default, Yarn fetches packages from the official npm registry. You can configure it to use other registries.

Commands / Usage

Project Initialization and Setup

yarn init: Initializes a new Node.js project. Prompts you for basic information and creates a package.json file.
```
yarn init
```
yarn init -y: Initializes a new Node.js project with default settings, skipping the prompts.
```
yarn init -y
```
yarn install: Installs all dependencies listed in package.json and yarn.lock. If yarn.lock exists, it installs the exact versions specified. If not, it resolves dependencies and creates yarn.lock.
```
yarn install
```
yarn install --frozen-lockfile: Installs dependencies exactly as specified in yarn.lock, failing if package.json and yarn.lock are out of sync. Useful for CI environments.
```
yarn install --frozen-lockfile
```
yarn install --production: Installs only production dependencies (ignores devDependencies).
```
yarn install --production
```

Adding and Removing Dependencies

yarn add <package-name>: Adds a package to your project’s dependencies and updates package.json and yarn.lock. Installs the latest version by default.
```
yarn add lodash
```
yarn add <package-name> --dev: Adds a package as a development dependency (to devDependencies in package.json).
```
yarn add jest --dev
```
yarn add <package-name>@<version>: Adds a specific version of a package.
```
yarn add react@17.0.2
```
yarn add <package-name>@^<version>: Adds a package with a caret semantic version range (e.g., ^17.0.2 allows 17.x.x but not 18.0.0).
```
yarn add express@^4.17.1
```
yarn add <package-name>@~<version>: Adds a package with a tilde semantic version range (e.g., ~17.0.2 allows 17.0.x but not 17.1.0).
```
yarn add axios@~0.21.1
```
yarn add <package-name> --exact: Adds a package with an exact version number, no range.
```
yarn add typescript --exact
```
yarn remove <package-name>: Removes a package from your project, updating package.json and yarn.lock.
```
yarn remove lodash
```
yarn remove <package-name> --dev: Removes a development dependency.
```
yarn remove jest --dev
```

Running Scripts and Commands

yarn <script-name>: Executes a script defined in the scripts section of your package.json.
```
# Assuming "test": "jest" is in package.json
yarn test
```
yarn <command> <args...>: Executes a binary from a package’s node_modules/.bin directory.
```
yarn eslint src/index.js
```
yarn dlx <package-name> [args...]: Executes a package’s binary without installing it globally or locally first. It downloads the package, runs the command, and then cleans up. Similar to npx.
```
yarn dlx create-react-app my-app
```

Updating Dependencies

yarn upgrade: Updates all packages to the latest versions allowed by package.json and yarn.lock.
```
yarn upgrade
```
yarn upgrade <package-name>: Updates a specific package to the latest version allowed by package.json and yarn.lock.
```
yarn upgrade lodash
```
yarn upgrade <package-name> --latest: Updates a specific package to its absolute latest version, ignoring package.json version constraints. This will update package.json and yarn.lock.
```
yarn upgrade lodash --latest
```
yarn upgrade --latest: Updates all packages to their absolute latest versions, ignoring package.json version constraints. This will update package.json and yarn.lock.
```
yarn upgrade --latest
```

Package Management and Information

yarn outdated: Lists packages that have newer versions available than what’s currently installed.
```
yarn outdated
```
yarn info <package-name>: Displays information about a package from the registry.
```
yarn info react
```
yarn list: Lists all the packages installed in your project, including their dependencies.
```
yarn list
```
yarn why <package-name>: Shows why a particular package is installed (which of your dependencies requires it).
```
yarn why react
```

Cleaning and Caching

yarn cache clean: Clears the Yarn cache. This forces Yarn to re-download packages the next time they are needed.
```
yarn cache clean
```
yarn cache list: Lists packages in the Yarn cache.
```
yarn cache list
```
yarn clean: Removes the node_modules folder and the yarn.lock file.
```
yarn clean
```

Publishing Packages

yarn publish: Publishes your package to the npm registry. Requires you to be logged in (yarn login) and have a publishConfig section in your package.json if you’re publishing to a scoped registry.
```
yarn publish
```
yarn publish --new-version <version>: Publishes a new version of your package.
```
yarn publish --new-version 1.2.3
```
yarn login: Logs you into a package registry (e.g., npm).
```
yarn login
```
yarn logout: Logs you out of a package registry.
```
yarn logout
```

Workspaces (Monorepos)

yarn workspaces list: Lists all workspaces in your monorepo.
```
yarn workspaces list
```
yarn workspace <workspace-name> <command>: Runs a command within a specific workspace.
```
yarn workspace @my-scope/ui add react
```
yarn workspaces foreach <command>: Runs a command in each workspace.
```
yarn workspaces foreach run build
```
yarn workspaces foreach --tag <tag> <command>: Runs a command in each workspace that has a specific tag.
```
yarn workspaces foreach --tag frontend run build
```

Common Patterns

Install project dependencies:
```
yarn install
```
Add a production dependency:
```
yarn add express
```
Add a development dependency:
```
yarn add typescript --dev
```
Run a script defined in package.json:
```
yarn start
yarn build
```
Run a linter on specific files:
```
yarn eslint src/
```
Update all packages to their latest allowed versions:
```
yarn upgrade
```
Update a specific package to its absolute latest version:
```
yarn upgrade react --latest
```
Check for outdated packages:
```
yarn outdated
```

Clean install (remove node_modules and yarn.lock, then reinstall):

yarn cache clean && rm -rf node_modules yarn.lock && yarn install

Install dependencies in a CI environment (ensuring lockfile is used):
```
yarn install --frozen-lockfile
```
Install only production dependencies:
```
yarn install --production
```

Gotchas

yarn.lock is crucial: Always commit your yarn.lock file to version control. It guarantees that everyone on your team and your CI/CD pipeline installs the exact same dependency versions, preventing "it works on my machine" issues.
Global vs. Local Installation: Yarn primarily manages local project dependencies. Avoid using yarn global add unless absolutely necessary, as it can lead to version conflicts and make projects less portable. Prefer using yarn dlx or adding dev dependencies to package.json for command-line tools.
yarn install vs. yarn upgrade: yarn install prioritizes the yarn.lock file. If it exists, it installs exactly what’s in the lock file. yarn upgrade respects the version ranges in package.json and updates yarn.lock accordingly.
--frozen-lockfile in CI: This flag is essential for CI/CD pipelines. It ensures that yarn install will fail if package.json and yarn.lock are not in sync, preventing unexpected dependency changes.
Cache Issues: If you encounter strange installation errors, yarn cache clean can sometimes resolve them by forcing a fresh download of packages.
Workspaces and yarn.lock: In a monorepo using workspaces, Yarn typically hoists dependencies to the root node_modules folder to save space and avoid duplication. This means the yarn.lock file at the root is the primary source of truth for all dependencies across all workspaces.