Package Manager – NPM and Yarn Explained with Examples

A package manager is a tool developers use to automate finding, downloading, installing, configuring, upgrading, and removing a system’s packages.

Why Do You Need a Package Manager?

Suppose there were no package managers. In that case, you would have to do the following manually:

• Find all the correct packages for your project
• Verify that the packages don’t have any known vulnerabilities
• Download the packages
• Install them to the appropriate location
• Keep track of new updates for all your packages
• Upgrade each package whenever there is a new release
• Remove the packages you no longer need

Manually managing tens or hundreds of packages is a tiresome and time-consuming endeavor.

Therefore, package managers—such as NPM, pNPM, Bower, and Yarn—help automate and eliminate the tedious process of managing all your packages manually.

Keep in mind that a package manager is not the same as a package registry. So, let’s find out the main difference below:

Package Manager vs. Package Registry – What’s the Difference?

A package manager is a tool developers use to automatically find, download, install, configure, upgrade, and uninstall a computer’s packages.

NPM (Node Package Manager) and Yarn (Yet Another Resource Negotiator) are two popularly used package managers.

A package registry is a database (storage) for thousands of packages (libraries, plugins, frameworks, or tools).

In other words, a package registry is the place packages get published to and installed from.

NPM registry and GitHub Packages are two popularly used package registries.

So, now that we know what a package manager is and why it is needed, we can discuss how to use the two popular ones—NPM and Yarn.

Note that there are numerous NPM vs. Yarn debates out there—so we will avoid them here because the best package manager is the one that works best for you.

Therefore, this article will show you how NPM and Yarn work rather than tell you which package manager is best. It is then up to you to decide which you prefer.

Alternatively, you can choose to use NPM for a specific project and Yarn for another—depending on which manager you believe is best suited for the job.

So, without any further ado, let’s begin by learning how to install the two managers.

Installing Node Package Manager (NPM)

NPM gets installed automatically while installing Node.

Therefore, to get NPM installed on your system, go to the NodeJS website and get Node’s latest LTS (Long Term Support) version.

Installing Yarn

It is best to install Yarn through NPM. So, first, install NPM from the Node.js website.

Once you’ve installed NPM, proceed to install Yarn like so:

npm install -g yarn

Checking the Installed Node Version

To check the Node.js version installed on your system, run:

node -v

The -v flag in the snippet above is a shorthand for --version.

Checking the Installed NPM Version

To check the NPM version installed on your system, run:

npm -v

The -v flag in the snippet above is a shorthand for --version.

Checking the Installed Yarn Version

To check the Yarn version installed on your system, run:

yarn -v

The -v flag in the snippet above is a shorthand for --version.

CodeSweetly ads

Upgrading Node Package Manager

Update to the latest NPM version by running:

npm install npm@latest -g

Upgrading NodeJS

Suppose you wish to upgrade your Node.js installation. In that case, you have two options:

Option 1: Upgrade via the NodeJS website

One way to upgrade your NodeJS installation is to manually download and install the latest version from the Node.js website.

Option 2: Upgrade via a version management tool

Another way to upgrade your NodeJS installation is to use a version manager such as NVM, n, and nvs.

Upgrading Yarn

Update to the latest Yarn version by running:

yarn set version stable

So, now that you have NPM (or Yarn) on your computer, we can start using the installed manager to find, install, configure, and remove our project’s packages.

But what exactly is a package? Let’s find out.

What Exactly Is a Package?

A package is a directory (or project) that has a package.json file used to record information about it.

Note

You can only publish packages (a project described by a package.json file) to the NPM registry.

Installing Packages

There are two ways to install a package: locally or globally.

Installing packages locally

A locally installed package is one that you can use only in the project in which you’ve installed it.

To install a package locally, do the following:

1. Navigate to the root directory of your project from the command line.
2. Install your package using the NPM or Yarn installation command below (depending on the package manager you’ve chosen to use for your project).

Note

You must have Node and NPM installed on your system for the NPM (and Yarn) installation commands below to work. You can get both by installing the latest LTS or the current version from the Node.js website.

NPM installation command

npm install package-name --save

Note that the --save command above instructs NPM to save package-name in the package.json file as one of the packages on which the project depends.

Suppose you wish to install an exact version of a package. In such a case, add a @[version-number] after the package’s name like so:

npm install [email protected] --save

Alternatively, if the package you are installing is for development and testing purposes, use:

npm install package-name --save-dev

The commands above will cause NPM to download three items into your project’s root directory: a node_modules folder, a package.json file, and a package-lock.json file.

Yarn installation command

yarn add package-name

Suppose you wish to install an exact version of a package. In such a case, add a @[version-number] after the package’s name like so:

yarn add [email protected]

Alternatively, if the package you are installing is for development and testing purposes, use:

yarn add package-name --dev

The commands above will cause Yarn to download three items into your project’s root directory: a node_modules folder, a package.json file, and a yarn.lock file.

But what exactly are the node_modules folder, package.json file, package-lock.json file, and yarn.lock file? Let’s find out.

node_modules

The node_modules directory is the folder where NPM places all the packages it downloads locally for your project.

package.json

The package.json file is where your package manager stores information about your project.

package-lock.json

The package-lock.json file is a document NPM uses to record the exact version of all the packages you’ve installed locally to your project’s node_modules directory.

A package-lock.json file makes an app 100% reproducible in the exact way you published it to the NPM registry.

So, suppose a user clones your app and runs the npm install command. In such a case, package-lock.json ensures that the user downloads the exact version of the packages you used to develop the application.

For instance, let’s say a user cloned your app containing no package-lock.json file, and a dependency used in the app has a newer version.

Suppose the dependency’s version number in the package.json file has a caret sign (for example, ^2.6.2). In that case, NPM will install the latest minor version of the dependency—which might cause the app to produce erroneous results.

However, suppose the user cloned your app containing a package-lock.json file. In that case, NPM will install the exact version of the dependency as recorded in the package-lock.json file—regardless of whether a newer version exists.

Therefore, users will always get your app the precise way you published it to the NPM registry.

In other words, NPM uses the package-lock.json file to lock your package’s dependencies to the specific version numbers you used for the project’s development.

Note

NPM will update the packages recorded in the package-lock.json file whenever you run the npm update command.

yarn.lock

The yarn.lock file is a document Yarn uses to record the exact version of all the packages you’ve installed locally to your project’s node_modules directory.

The yarn.lock file is comparable to NPM’s package-lock.json lockfile.

So, now that we know how to install a package locally, we can discuss the global package installation.

Installing packages globally

A globally installed package is a package that you can use anywhere on your system.

To install a package globally, run the code below on your terminal:

npm install package-name -g

Alternatively, you can use Yarn like so:

yarn global add package-name

Note that you can run the commands above from any location on your system.

Local vs. global package installation

Generally, it is better to install a package locally. Below are some of the differences between a local and global installation.

1. Installation location

A locally installed package gets installed in the directory where you executed the npm install package-name (or yarn add package-name) command.

Specifically, you will find a project’s locally installed packages in its node_module directory.

In contrast, a globally installed package gets installed in a single location on your system. The exact location depends on your system’s configuration.

2. Package versions

Suppose you installed your package locally. Then, you can use different versions of the same package for multiple app development.

However, you are forced to use the same package version for all your apps when you install globally.

3. Updates

A local installation allows you to choose the project whose package you wish to upgrade to the latest version. Thus, making it easier to manage upgrades that break compatibility with other packages.

However, upgrading a globally installed package updates the package for all projects—which can cause maintenance nightmares if the upgrade breaks compatibility with other packages.

4. Usage recommendation

Global installation is best for packages you intend to use only on your command line—especially when they provide executable commands reusable across projects.

However, local installation is best for packages you intend to use in your program—through the import statement or require() function.

5. Examples

NPM, React Native CLI, Gatsby CLI, Grunt CLI, and Vue CLI are well-known examples of global packages.

Common examples of local packages are Webpack, Lodash, Jest, and MomentJS.

Note

• You can do both local and global installation of packages you intend to use both on the command line and in your project. Typical examples of such packages are Express JS and CoffeeScript.
• Your package manager does not execute an installed package. NPM (and Yarn) only install packages to the node_modules directory. And if you had specified the --save command, your manager will add details about the package to the package.json file.
• To execute (run) any executable package, you must explicitly do so yourself. Find out how in the following section below.

Running an Executable Package

There are several ways to run an executable package. Below are the standard techniques.

Technique 1: Manually locate and execute the package

One way to run an executable package is to type its local path on your command line like so:

./node_modules/.bin/name-of-package-to-execute

Technique 2: Add the package to the package.json’s scripts field

An alternate way to execute a package is to first add it to the "scripts" field of your project’s package.json file like this:

{
  "name": "your_package",
  "version": "1.0.0",
  "scripts": {
    "desired-name": "name-of-package-to-execute"
  }
}

Afterward, you can run the package like so:

npm run desired-name

Note that the command above is a shorthand for npm run-script desired-name.

Alternatively, you can execute the package with Yarn like so:

yarn run desired-name

Here’s an example:

{
  "name": "codesweetly-app",
  "version": "1.0.0",
  "scripts": {
    "build": "webpack"
  }
}

The snippet above added webpack to our package.json’s "scripts" field. So, we can now execute webpack on the command line like so:

npm run build

Or, if your package manager is Yarn, you can run webpack like this:

yarn run build

Technique 3: Use NPX

A faster way to run an executable package is to use NPX like so:

npx package-name

With NPX, you no longer need to add your package to the "scripts" field of your project’s package.json file.

NPX (Node Package Execute) is a Node package runner that automatically finds and executes a specified package.

Note

NPX automatically gets installed when you install Node 8.2/NPM 5.2.0 or higher.

Here’s an example:

npx webpack

The command above will automatically find and execute webpack. So, we do not need to add the "build": "webpack" property to the "scripts" field of our package.json file.

NPX also allows you to run some code using your preferred Node.js version. Let’s find out how.

How to Run Some Code Using Your Preferred Node.js Version

You can use the @ character and the node npm package to specify the Node.js version you wish to use to execute your code.

Here’s an example:

npx node@7 index.js

The snippet above tells NPX to run index.js with the latest version of Node from version 7 major.

Using the node@ command is a helpful way to avoid using Node.js version management tools like nvm to switch between Node versions.

Suppose you wish to confirm the Node version NPX will use to run your code. In that case, run:

npx node@7 -v

The snippet above will display the latest Node version from version 7 major that NPX will use to run your code—for example, v7.10.1.

Checking an App’s Locally Installed Packages

Here are three ways to see an app’s locally installed packages:

1. Display locally installed packages and their dependencies

npm list

Or use Yarn like so:

yarn list

2. Display locally installed packages—without their dependencies

npm list --depth=0

Or,

yarn list --depth=0

3. Check if a specific package got installed locally

npm list package-name

Checking an App’s Globally Installed Packages

Here are three ways to see an app’s globally installed packages:

1. Display globally installed packages and their dependencies

npm list -g

Or use Yarn like so:

yarn list -g

2. Display globally installed packages—without their dependencies

npm list -g --depth=0

Or,

yarn list -g --depth=0

3. Check if a specific package got installed globally

npm list -g package-name

Checking for Outdated Local Packages

To determine if any of your project’s packages are outdated, run:

npm outdated

If the command outputs nothing, it means all your project’s packages are up to date.

Otherwise, see this npm-outdated article for a detailed explanation of the command’s output.

Alternatively, you can use Yarn like so:

yarn outdated

Note

To check a specific package’s outdated status, add the package’s name after the outdated keyword—for example, npm outdated lodash.

Checking for Outdated Global Packages

To confirm which global package is outdated, run:

npm outdated -g --depth=0

Updating Packages

Here’s how to update packages with NPM and Yarn:

Updating a package to a specific version

Add a @[version-number] after the package’s name:

NPM Command

npm install [email protected]

Yarn Command

yarn add [email protected]

The command above will update the specified package to version 4.14.3.

Updating a package to its latest version

npm update package-name

Or, for projects managed with Yarn, run:

yarn upgrade package-name

The commands above will update the specified package to its latest version according to the version range defined in the package.json file.

Suppose you wish to ignore the version range defined in the package.json file. In that case, use the following command:

npm install package-name@latest

Or,

yarn upgrade package-name --latest

The commands above tell NPM (or Yarn) to ignore the version range in the package.json file. Instead, it should update the specified package to the version with the latest tag.

Caution

Ignoring the package.json version range may cause your package manager to upgrade to a major breaking change version.

Updating all of a project’s locally installed packages to their latest versions

npm update

Or,

yarn upgrade

The commands above will update a project’s packages to their latest versions according to the version ranges defined in the package.json file.

Updating a globally installed package

You can update a globally installed package like this:

npm update package-name -g

Updating all your system’s globally installed packages

npm update -g

Uninstalling Packages

Here’s how to uninstall packages with NPM and Yarn:

Uninstalling a package from a specific project

First, navigate to the project’s root directory from the command line and run:

npm uninstall package-name

Note

• Add the -S (or --save) flag to remove references to the package in the dependencies field of the project’s package.json file.
• Add the -D (or --save-dev) flag to remove references to the package in the devDependencies field of the project’s package.json file.

For projects managed with Yarn, run:

yarn remove package-name

Note

The yarn remove command will automatically update the project’s package.json and yarn.lock files.

Uninstalling a global package

npm uninstall package-name -g

Note that it is best practice not to remove packages manually from the node_modules folder as such action can affect other modules depending on it.

But what exactly is a module in NodeJS? Let’s find out below.

CodeSweetly ads

What Exactly Is a Module in NodeJS?

A module in NodeJS is any file in the node_modules folder that the computer can load through Node’s require() function.

Here’s an example:

const myModule = require("./codesweetly.js");

Suppose the computer successfully used the require() function to load the codesweetly.js file. In such a case, it means codesweetly.js is a module—assigned to the myModule variable.

Publishing Your Project to the NPM Registry

NPM is a free registry for public package authors.

So, you can use it to publish any project (folder) from your computer that has a package.json file.

Below are the steps required to share your package with the world.

1. Sign in or sign up

   Go to the NPM website and sign in (or sign up if you do not yet have an account).

   Note

   Make sure that you verify your email after creating a new account. Otherwise, you will get a 403 Forbidden error while publishing your package.

2. Log in

   Login to your NPM account from the command line like so:

   npm login

   Note

   You can use the npm whoami command to check if you are currently logged in.

3. Publish your package!

   Go to your project’s root directory and publish it like so:

   npm publish

Make sure your package’s name does not currently exist on NPM. Otherwise, you will get an error while publishing.

You can use the npm search command (or the NPM website’s search bar) to search if the name you wish to use already exists on NPM.

Suppose all the suitable names for your package are already taken. In that case, NPM allows you to publish your project as a scope.

In other words, you can publish your package as a sub-section of your NPM username. Let’s see how below.

Publishing your package as a scope of your NPM username

Open your package.json file and prefix your package’s name with your NPM username.

Here’s an example:

{
  "name": "@username/package-name",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT"
}

NPM’s default setting assumes that a scoped name package is a private project. So, you will get an error if you use the npm publish command to share a scoped name package.

Therefore, to publish your package as a scope of your username, add the --access=public flag to the npm publish command:

npm publish --access=public

Note

You can make your project a scoped package during the initialization process by using the npm init --scope=username command instead of npm init.

Switching from Yarn to NPM

Here are the steps to migrate your package manager from Yarn to NPM.

1. Run the npm install command to configure your node_modules directory with NPM’s resolution algorithm.
2. Delete your project’s yarn.lock file.
3. Open your package.json file and replace all the Yarn commands in the "scripts" field with their NPM alternatives.

Switching from NPM to Yarn

Here are the steps to migrate your package manager from NPM to Yarn.

1. Run the npm install -g yarn command to install Yarn globally on your system.
2. Run the yarn or yarn add command to configure your node_modules directory with Yarn’s resolution algorithm.
3. Delete your project’s package-lock.json file.
4. Open your package.json file and replace all the NPM commands in the "scripts" field with their Yarn alternatives.