WittCodešŸ’»

npm Local vs Global Packages

By

Learn what local and global npm packages are, the difference between local and global packages, where they are installed, and when to install an npm package locally vs globally.

Table of Contents šŸ“–

Creating a JavaScript Project

To better demonstrate local and global packages with npm, lets create an npm package by creating a directory called local-global and running npm init -y.

mkdir local-global
cd local-global
npm init -y

The command npm init -y creates a package.json file and supplies it with default information about this project. This package.json file will list our local installations.

npm Local Packages

In npm, a local package is a package that is installed by using npm install <package_name>. Packages installed locally are only available to the project they were installed under. For example, we can install express locally like so.

npm install express

When a package is installed locally, it is listed inside package.json under dependencies or devDependencies. Inside package.json, look for the following.

"dependencies": {
    "express": "^4.18.1"
}

So, express is only available to this project as it was installed locally. If we created another npm project called local-global-2 and tried to require express, we would get a module not found error. We can also install packages locally as a devDependency by tagging on --save-dev to npm install. Lets do this with ESLint.

npm install eslint --save-dev

Now, if we look inside package.json, ESLint should be listed under devDependencies.

"devDependencies": {
    "eslint": "^8.17.0"
}

Packages listed under devDependency mean that they are required for development of the project but they are not needed by the project when it is out in production.

Where are Local Packages Installed?

When packages are installed locally, they are placed inside the folder node_modules.

The node_modules folder is what npm uses to keep track of packages that have been installed locally. When packages are installed locally from npm they are copied into the node_modules folder. Node then looks inside node_modules for a specific package when it is required. For example, if we create an index.js file and require express, node will look inside node_modules.

// Node looks inside node_modules for express
const express = require('express');

The contents of node_modules changes whenever the dependencies are changed in package.json and npm install is ran. Also, if we look inside node_modules, we will see a lot more packages besides express and eslint. This is because as of npm version 3, the dependencies of project dependencies, or sub-dependencies, are installed top level. Only when there are conflicts the sub-dependencies will be installed at deeper levels.

What are Global Packages?

Global packages are only present in a single place in a system. They are installed by tagging on -g to npm install. Lets install the package nodemon globally.

npm install nodemon -g

Where are Global Packages Installed?

We can see where global packages are installed on a system by running npm root -g.

npm root -g

The npm root command prints the effective node_modules folder to the console. If we tag on -g, it prints the location of the global node_modules. The output from this command will differ depending on the operating system of the computer and the way that node was installed. For example, if nvm is listed in the path, node was most likely installed through nvm.

/home/wittcode/.nvm/versions/node/v14.15.3/lib/node_modules

How to List Global Packages

Global packages present on a system can be listed by the command npm list -g --depth 0.

npm ls -g --depth 0

The npm ls command lists installed packages. Tagging on -g lists the global packages and --depth determines how far down the dependency tree we want to go. Providing --depth the value 0 tells npm to just display the top level packages (not any sub-dependencies). This should give output similar to the following.

/home/wittcode/.nvm/versions/node/v14.15.3/lib
ā”œā”€ā”€ node-gyp@9.0.0
ā”œā”€ā”€ nodemon@2.0.15
ā””ā”€ā”€ npm@6.14.9

Install a Package Locally or Gloablly?

As a general rule, all packages should be installed locally. This is because installing packages locally allows for different versions of a package to be used in different projects. If several projects all relied on a global package and that package was updated, there could be some breaking changes.

When to Install a Package Globally?

This doesn't mean a package should never be installed globally. A package should be installed globally when it contains an executable that is run from the CLI and is reused across multiple projects. For example, a common package to be installed globally is nodemon, a tool that automatically restarts a node application after files have been changed.

Summary

But there we have it! The ability to install npm packages locally and globally is extremely useful. If this article was helpful, please consider donating by using the link at the top of the page, sharing this article, and subscribing to my YouTube channel WittCode.