Code Monkeys

# Installing Yarn 1

By: Jay the Code Monkey
•Posted: Dec 28, 2021 •Updated: Apr 18, 2023

# What is a Package Manager?

Before discussing Yarn (opens new window) in more detail, let's first define what a package manager is and what it handles for us.

A package manager is a tool that allows developers to manage a project's dependencies.

Dependencies also known as packages are programs that a project relys on to function properly.

Using dependencies makes development easier since you can use other developer's solutions for implementing features in your project.

A package manager handles the following for your packages:

  • Installing
  • Updating and upgrading
  • Uninstalling
  • Configuring

# What is Yarn?

Yarn (opens new window) is a package manager designed with three main goals in mind:

  • Speed
  • Security
  • Reliability

Like other package managers, Yarn (opens new window) allows you to use and share code with other developers which again makes development easier. The code is shared using a package.json file which describes the dependencies used in a project.

Yarn (opens new window) is an alternative to npm (opens new window) which is the default node package manager for Node.js (opens new window). It was originally developed to address the performance and security issues with npm (opens new window).

This post will cover the installation and some commands for Yarn 1 (opens new window).

Yarn 1 Maintenance Mode

Yarn 1 (opens new window) is officially in maintenance mode, so no further updates will be released unless they are needed to patch vulnerabilities. If you're starting a new project, it's recommended to use the latest stable version which at the time of this writing is Yarn 3 (opens new window).

If you're interested in learning more about the release history of Yarn (opens new window) and npm (opens new window), then check out the section below.

# Timeline of Yarn and npm Development

When Yarn (opens new window) was released in 2016 it achieved its goals of being a faster, more secure, and more reliable alternative to npm (opens new window). The improved reliability was accomplished by generating a yarn.lock file which handles keeping track of the exact versions of packages used in a project.

In 2017, npm (opens new window) addressed its speed and reliability issues with the release of npm 5 (opens new window). The reliability issue was addressed with the introduction of the package-lock.json file which provided similar functionality to the yarn.lock file.

In 2018, npm (opens new window) addressed its security issues with the release of npm 6 (opens new window) by checking vulnerabilities before installing dependencies as well as introducing more improvements to speed and reliability.

Yarn 2 (opens new window) and npm 7 (opens new window) were both released in 2020 with improved performance and some new features as well.

In 2021, Yarn 3 (opens new window) and npm 8 (opens new window) were released which again introduced improved performance and some new features.

Today, the performance and features of Yarn (opens new window) and npm (opens new window) are very similar, so which one to use mainly depends on a developer's preference.

# Installation

There are multiple ways to install Yarn 1 (opens new window). Currently, the recommended way to install it is with npm (opens new window) the default node package manager that comes with Node.js (opens new window). When installing Node.js (opens new window) you have the option to install a system version which you can do by downloading and installing a version directly from Node.js (opens new window), or you can install multiple node versions with a node version manager.

Using a Node Version Manager

If you're a developer that needs to use multiple versions of node when working on different projects, then I recommend installing either nvm (opens new window) or fnm (opens new window). My preferred way to manage my node versions is with fnm (opens new window). If you're interested in installing a node version manager, then check out these posts Installing Node Version Manager (nvm) and Installing Fast Node Manager (fnm).

After installing a system version or a version with a node version manager, you can run the following command to install and upgrade Yarn 1 (opens new window):

This will install Yarn 1 (opens new window) globally. We'll see how to install a specific local version of yarn in the root of a project directory when looking at the usage of yarn.

Resolving Permissions Error

If you're using a system version, you may get a permissions error when attempting to install with npm (opens new window). To resolve this check out the installation (opens new window) documentation for platform-specific methods for Linux, macOS, and Windows. Alternatively, you can uninstall your system version and use a node version manager instead.

# Platform Installation Notes

When using a platform-specific method a version of Node.js (opens new window) will also be installed. To avoid the Node.js (opens new window) installation some platform-specific methods have the option of ignoring it by passing certain commands. See the installation (opens new window) documentation for more details on ignoring the Node.js (opens new window) installation, configuration requirements, and possible issues.

If the option to ignore the installation of Node.js (opens new window) is not available for your preferred platform-specific method, then you can uninstall your system version and just use the platform-specific method to install both Yarn 1 (opens new window) and Node.js (opens new window).

If you prefer to use a platform-specific method with a node version manager, then you should only use a method that can ignore the installation of Node.js (opens new window) since it can cause conflicts.

# Usage

Now we'll be discussing some useful and common commands to get you started with Yarn 1 (opens new window).

# Help Commands

Here's how to access the help documentation for the yarn command which is always useful and recommended to do for any installed tool.

Run the following command to see a list of commands, flags, and descriptions for yarn:

To see help information for a specific subcommand run the following:

# Check Yarn Version

To verify your installation was successful and to check your version of yarn run the following command:

# Setting a Local Version

To install and set a local version of yarn for a specific project you can use the global yarn command we installed earlier. This ensures everyone working on a project is using the exact same version of yarn which is useful to avoid any undesired behavior like producing a different yarn.lock file.

This is accomplished by using yarn policies (opens new window) which allows you to check in your Yarn 1 (opens new window) release within your repository. After running the command below in your project's root directory, a single-file release from the GitHub repository will be downloaded and stored in your project in a .yarn/releases directory. Then your yarn-path will be updated in a .yarnrc file.

Now any yarn command run in your project will be using the local version that you set. Be sure to push these changes to your project's remote branch, so everyone using the project will be downloading and using the same version of Yarn 1 (opens new window) as you.

If you're using an existing project, then you don't need to set the local version as long as the project has the desired version of Yarn 1 (opens new window) in the .yarn/releases directory, and the yarn-path is configured properly in the .yarnrc file.

If you don't have a project directory, then run the following:

Next, navigate to your project:

Now, set the version of Yarn 1 (opens new window) for your project:

There are multiple ways to specify which version you want to use:

  • yarn policies set-version downloads the latest stable release
  • yarn policies set-version --rc downloads the latest rc release
  • yarn policies set-version 1.22.4 downloads a specific version

Running yarn policies set-version [version] is also the recommended way to upgrade your version of Yarn 1 (opens new window).

Now run yarn --version in your project directory, and it should output the local version you just set. If you navigate out of your project directory and run yarn --version, then you should see the global version that you installed.

The global version of yarn will first check if it's in a directory with a .yarnrc file. If the directory has a .yarnrc file, then the configured yarn-path value will be used to switch the yarn version from the global version to the project specific version.

Resolving Installation Directory Issue

If you set the local version in your project's root directory and the .yarn directory and .yarnrc file aren't generated there, then delete the files that were generated and run the yarn init command in your project's root directory before setting the local version. The yarn init command is described in the Creating a New Project section.

# Updating the .gitignore File

After setting your local version of yarn, you should now have .yarn directory in the root of your project.

Some of the files yarn adds to your .yarn directory should be checked into version control, e.g., git and others should be ignored.

To specify which directories and files should be ignored when pushing to your repositiory you can create a .gitignore file.

After creating the .gitignore file, you can add the recommended basic configuration for yarn:

This will ignore the entire .yarn directory except for the directories specified after the !.

The yarn.lock and .yarnrc files should always be checked into version control.

# Adding a .gitattributes File

If you're using a local version of yarn, then it's recommended to add a .gitattributes file to your project which will prevent git from showing large diffs when you add or update releases and plugins:

This is accomplished by identifying the release and plugin directories as binary content.

# Creating a New Project

To create a new project first create and navigate to the project directory. See the commands above for creating and navigating to a project directory.

Then run the following command:

After running the above command, you'll be asked to answer several questions. You can enter custom values for each question or press enter to accept the defaults. Here's an example of running the command in a directory named project-directory:

After answering all of the questions, a package.json file containing the answers will be created. The package.json file contains metadata about your project. This metadata includes information used to identify and describe your project and the packages you install which follow semantic versioning (semver) (opens new window).

Now, let's describe each property in a little more detail:

  • name is the name given to your project
    • Must be less than or equal to 214 characters including the @scope/ for scoped packages (opens new window)
    • Cannot start with a dot or an underscore
    • Must contain only lowercase letters and URL-safe characters
    • If the project is published to npm (opens new window), it gets a URL based on the given value which is the reason for the requirements given above
    • The default value is the same name as the directory you're in when running the yarn init command
  • version indicates the current version of your project
  • description is used to describe and provide more information about your project
    • Especially useful to include if you plan on publishing your project to npm (opens new window)
    • If no value is given, it will not be set
  • entry point is a JavaScript file that starts the execution of your project
    • This property is called main in the package.json file
    • The default value is index.js
  • repository url describes the location of the project repository containing the code
    • This property is called repository in the package.json file
    • You can explicitly set the URL and a version control type in the package.json file by adding, e.g., "repository": { "type": "git", "url": "https://github.com/github-username/my-new-project" }
    • If no value is given, it will not be set
  • author describes the creator or owner of the project
    • Used to describe one person
    • You can explicitly set the author name, email, and website in the package.json file by adding, e.g., "author": { "name": "Your Name", "email": "youremail@example.com", "url": "https://your-website.com" }
    • If no value is given, it will not be set
  • license indicates the type of license being used by the project
    • Allows users to know how they're permitted to use the project
    • Check out Choose a License (opens new window) if you need help determining how you should license your project
    • The default value is MIT
  • private indicates whether or not the project can be published to npm (opens new window)
    • If set to true, it will prevent the project from being published
    • If no value is given, it's assumed the value is false, and it will not be explicitly set in the package.json file

If you're interested in learning more about the package.json file, then check out The package.json guide (opens new window) and the Yarn 1 package.json (opens new window) documentation. Also, check out the Versions of dependencies (opens new window) documentation for more information about how semver (opens new window) is used.

Here's the contents of the package.json file from the example above:

To update the package.json file you can open and edit it directly, or you can run the yarn init command again.

Check out the yarn init (opens new window) documentation for more information about the command.

# Adding Packages

When adding a package the package.json file gets updated by adding the package as a dependency to a dependencies object where each key is a package name and the value represents a range of allowed versions following semver (opens new window) notation.

A yarn.lock file will also be created if it doesn't exist or updated if it already exists. A yarn.lock file is used to keep track of the exact versions of packages added to a project. This allows consistent installs across machines by allowing developers to have the exact same versions of packages when installing all of a project's dependencies.

Here's how to handle the yarn.lock file in your project:

  • The yarn.lock file should be in the root of your project directory
  • You shouldn't directly edit the yarn.lock file it gets auto-generated and automatically updated
  • When installing only the top-level yarn.lock file is used and any yarn.lock files that exist in the dependencies will be ignored
  • The yarn.lock file should also be checked into version control since it's used to install the exact same versions of packages across machines

To add the latest version of a package run the following command:

To add a specific version of a package run the following command:

To add the latest version of a package within a specified version range run the following command:

The latest version within the given version range is determined by the range specifier and the version number.

In the example above the range specifier is the caret symbol, i.e., ^. You can use any desired range specifier, and the added package will be the latest version within the given version range.

You can also add a package with a specific tag by running the following command:

Tags are a way to mark published versions of a package with a label. Check out the yarn tag (opens new window) documentation for more information about them.

To add a package to your development dependencies, i.e., devDependencies you can add either the --dev or -D flag to the end of the command.

Development dependencies are dependencies that you need for the development workflow, e.g., Babel (opens new window), but not while running the project.

Here's an example of adding the latest version of a package to your devDependencies:

See the Types of dependencies (opens new window) documentation for more information about them.

To add a package globally to your operating system you can use the global subcommand before add:

When to Use Global

In general you should be adding packages locally because anyone else using your project will then get the same packages. If you install a package globally it will be available globally on your operating system, but it won't be available to anyone else using your project. You should only install a package globally if it's for developer tooling that isn't used for only a specific project, e.g., nodemon (opens new window). See the yarn global (opens new window) documentation for more details.

Check out the yarn add (opens new window) documentation for more information about adding packages.

# Listing Added Packages

To list all of your added packages in your project run the following command:

This will list all of the packages you added as well as their dependencies for the current working directory.

To list only the packages you explicitly added you can use the --depth flag as follows:

The above will restrict the depth of the displayed dependencies to be the first level. Notice that the levels are zero-indexed.

To learn more about listing added packages check out the yarn list (opens new window) documentation.

# Upgrading Packages

The upgrade subcommand will update the packages to their latest version based on the version ranges defined in the package.json file. See the Versions of dependencies (opens new window) documentation to get a better understanding of how version ranges are used.

After running the upgrade subcommand, the yarn.lock file will be updated with the latest versions specified by the version ranges. The versions in the package.json file will remain the same though since the upgraded packages will still be within the same version ranges.

To view the upgraded versions of your packages in a readable format you can use the yarn list command described in the previous section.

We'll see how to upgrade packages to versions outside of the specified version ranges which will update both the yarn.lock file and the package.json file.

The following command upgrades all packages within their specified version ranges:

You can also upgrade a specific package within its specified version range:

To upgrade all packages to their latest versions you can add the --latest flag:

You can also upgrade a specific package to its latest version using the --latest flag:

When using the --latest flag, the version range in the package.json file will be ignored. This can potentially result in the packages being upgraded across major versions which can lead to potential incompatible API changes, so be sure to check the packages for any breaking changes.

Since the range versions in the package.json file are ignored, both the yarn.lock and package.json files can be updated.

Also, the range specifiers in the package.json file will remain the same if it is still compatible with the latest version. If the range specifier isn't compatible with the new version a caret range specifier, i.e., ^ will be used instead.

So, e.g., a tilde range specifier, i.e., ~ will still be used for any packages that we're using it previously.

You can also explicitly set the range specifier by passing a flag after the --latest flag, e.g., --caret.

You can also upgrade a package to a specific version with the following command:

To upgrade a package to the latest version within a specified version range run the following:

The latest version within the given version range is again determined by the range specifier and the version number.

In the example above the range specifier is the caret symbol, i.e., ^. You can again use any desired range specifier, and the package will be upgraded to the latest version within the given version range.

You can also upgrade a package to a specific tag using the following command:

Tags are again a way to mark published versions of a package with a label. Check out the yarn tag (opens new window) documentation for more information about them.

You can specify a preferred range specifier when upgrading a package with a tag by passing, e.g., --tilde flag at the end of the command.

Downgrading Packages

Using specific versions and tags when upgrading packages also allows you to downgrade your package by specifying a version that is older than your currently installed version.

To learn more about upgrading packages check out the yarn upgrade (opens new window) documentation.

# Removing Packages

To remove a package run the following command:

After running the command above, the yarn.lock and package.json files will both always be updated. This ensures all developers will still be using the exact same versions of the packages.

Also, when removing a package it will be removed from all types of dependencies, e.g., dependencies, devDependencies, etc.

See the Types of dependencies (opens new window) documentation for more information about dependencies and the yarn remove (opens new window) documentation for more information about the command.

# Installing All Project Packages

The following command should be run when checking out code for a new project and when another developer adds or removes a package.

Run the following command to install all of a project's packages specified in the package.json file:

You can also just run the following:

After running either one of the commands above, a node_modules directory will be created in the current directory which contains all of the code for the installed packages.

Here's how the yarn.lock file is used:

  • If the yarn.lock file is present and if it contains all of the packages specified in the package.json file, then the exact versions specified in the yarn.lock file will be installed.
  • If there is no yarn.lock file or there is one that doesn't contain all of the packages in the package.json file, then the newest versions within the version ranges specified in the package.json file will be installed. This will then update the yarn.lock file.

To ensure the yarn.lock file is not updated when installing all of a project's dependencies you can run the following:

For more information about installing all the packages in a project check out the yarn install (opens new window) documentation.

# Running Scripts

To run a script you need to first add a scripts object to your package.json file. Then you can add each script as a key-value pair where the key is the name of the script you want to run, and the value is a command that gets run in your shell.

Here, we have defined two scripts in our scripts object with the names of test and build and with the commands of test-script and build-script, respectively.

To run a script you can run the following command:

You can also just run the following:

Potential Shorthand Issue

Built-in CLI commands will have preference over your scripts if they share the same name. To avoid running a built-in CLI command you can always include the run subcommand when running your scripts.

It's also possible to list all of the scripts available to run in your project by running the following:

See the yarn run (opens new window) documentation to lean more about the command and the yarn test (opens new window) documentation for more information about testing.

Made by & for Code Monkeys 🐵