How To Use npm to Manage Node.js Packages on a Linux Server

Introduction

Node.js is a popular Javascript platform for server-side programming that allows you to build and run web apps quickly. In a past guide, we discussed how to install Node.js on an Ubuntu 14.04 server.

In this guide, we will talk about how to use npm, a Node.js package management system, to manage Node.js packages on your server. Using this utility, you can easily satisfy application dependencies, search for packages, and manage installations.

We’ll assume that you have both Node.js and npm installed. You can follow the guide above to get these running on Ubuntu 14.04. I recommend using the nvm method covered in that tutorial.

If you just want to get started quickly, you can also find the packages in Ubuntu 14.04’s repositories and install them by typing:

sudo apt-get update
sudo apt-get install nodejs npm

Getting Familiar with npm

Now that you have the necessary components installed, we can get started.

The first thing we are going to do is add some npm auto-complete functionality to our shell by adding some information to the bottom of our shell configuration file.

You can do that by typing:

npm completion >> ~/.bashrc

Now, just source the configuration file to re-read the new changes you just added:

source ~/.bashrc

Now, npm should be able to automatically complete its commands by hitting the [TAB] key.

To get ourselves oriented, the best thing to do is get familiar with the help functionality that npm provides. To get an idea of the subcommands that are available within npm, you can type:

npm help

---

Usage: npm <command>

where <command> is one of:
    add-user, adduser, apihelp, author, bin, bugs, c, cache,
    completion, config, ddp, dedupe, deprecate, docs, edit,
    explore, faq, find, find-dupes, get, help, help-search,
. . .

To get a brief summary of what these subcommands mean, you can type:

npm -l

---

Usage: npm <command>

where <command> is one of:

    adduser     npm adduser
                Then enter stuff at the prompts

    bin         npm bin
                npm bin -g
                (just prints the bin folder)
. . .

You can get a much more extensive overview of each of these commands by using the following format:

<pre> npm help <span class=“highlight”>subcommand</span> </pre>

This will bring up a separate man page for the desired subcommand.

If you don’t know which command covers the action you wish to perform, you can also search within the help topics by using something like:

<pre> npm help-search <span class=“highlight”>search_term</span> </pre>

Finding Information about your System

Now that you have set up and know how to access its built-in help, we can explore. Let’s start by learning how to ask for information about our system that relates to npm.

Before we do that, we should talk about the difference between local and global packages.

Local vs Global Packages

When creating a Node.js application, you create a directory structure to hold your application. Within the project’s directory, there will be a subdirectory called node_modules. This holds all of the modules that you can install locally for your project.

Let’s create an empty directory structure that will serve as our package directory as an example:

mkdir -p ~/projects/test_package/node_modules
cd ~/projects/test_package

Modules installed locally can be used within your project by using the regular Javascript require() method. This is what you need most of the time for a package.

If you need to use a package’s command line capabilities, you should install it globally. Globally installed applications are kept in the ~/.npm/ directory. Their command line functions will be available to all of the Node.js applications. Globally installed packages cannot be used with the Javascript require() though.

Knowing this, you can see how we will have functionality that is associated with each specific type of package. By default, most npm commands will assume that you are talking about local packages, unless you pass the -g or --global flags.

Listing Packages Installed on our System

Now that you know the difference between local and global packages, we can move on. So, to list the (locally installed) Node.js packages available in our test_package directory, we can type:

npm ls

---

/home/demouser/projects/test_package
└── (empty)

Since we haven’t installed any Node.js packages for our application yet, this shows up empty.

However, npm installs some packages globally automatically. Let’s pass the -g flag to see:

npm ls -g

---

/home/demouser/.nvm/v0.11.13/lib
└─┬ npm@1.4.9
  ├── abbrev@1.0.4
  ├── ansi@0.2.1
  ├── ansicolors@0.3.2
  ├── ansistyles@0.1.3
  ├── archy@0.0.2
. . .

As you can see, there are quite a few global packages. They are shown in a dependency tree format.

There are some other options you can use to modify the output. You can use the -l or -a flags to get additional information. You can view this information in JSON by optionally passing the --json flag.

Querying for Other Information

Apart from simply asking npm about installed packages, we can ask it some other information about its environment.

We can see what npm refers to as the root module directory within the local package hierarchy by typing:

npm root

---

/home/demouser/projects/test_package/node_modules

You can get the top-level path for the package you’re working on by using the prefix subcommand:

npm prefix

---

/home/demouser/projects/test_package

These can also be used with the -g flag to see where the global files are stored.

To see where npm will install executables, you can find the bin directory for the current project:

npm bin

---

/home/demouser/projects/test_package/node_modules/.bin

Exploring a Package’s Files

To quickly go to the directory location where a package is installed, you can actually just use the explore subcommand. This will open a subshell in the directory where the package is installed.

For instance, we can open a subshell in the directory where npm itself is installed by typing:

npm explore -g npm

---

Exploring /home/demouser/.nvm/v0.11.13/lib/node_modules/npm
Type 'exit' or ^D when finished

You can manipulate or explore the files in this directory and then exit out of the subshell to return to what you were previously doing.

exit

Using npm as a Package Manager

We’ve covered a lot of ground so far, but we’ve skirted the main functionality of npm until now. The main reason that people use npm is for its package management capabilities.

Searching for and Installing Packages

When you need a Node.js package, you can search for it using npm. Let’s pretend we’re going to need the express package for our project. Express is a web framework.

We can search for this package in the npm package archives, which are located at the npm website:

npm search express

This will actually return an extremely long list, since express is a very popular package. You can pipe this into a pager like less to view it easier. We can also use regular expressions (with some funky characters to escape shell interpretation) like this:

npm search /^express\[\ \]

---

NAME    DESCRIPTION                                AUTHOR          DATE       VERSIO
express Sinatra inspired web development framework =tjholowaychuk… 2014-05-12 4.2.0

If you are getting too many results though, it might be easier just to go to the npm site to see what the exact package is called.

When you know the name of the package, you can install it. Since we need the command line functionality of express, we’ll install it globally:

npm install -g express

This will download and install the express package and all of its dependencies into the global npm root directory.

If we want the package in our local application’s module directory so that it can be included in the app with a require() line, you can type:

cd ~/projects/test_package
npm install express

We don’t actually need to install the package and dependencies in both places however, and we’ll show you how to avoid this below.

Uninstalling, De-duplicating, Pruning, and Linking Packages

Since we want this package in both our global and local scope, we need to provide it with a way to have this package available in both places.

First, let’s uninstall our local version of the package, like this:

npm uninstall express

Now, we can tell npm that we want to link our global copy to the local package, like this:

npm link express

This will create a symbolic link within our node_modules directory to our global package, making it available in both places.

We could have done the reverse of this by uninstalling the global version, going into the local package and linking globally. We could do that like this.

First, uninstall the local link and the global package:

npm uninstall express       # This removes the symbolic link in local
npm uninstall -g express    # This removes the actual package in global

Reinstall the package as a local package:

npm install express

The package is in our local application directory (~/projects/test_package/node_modules), but not installed globally. We can link it globally to going to the package directory and calling the link subcommand with no additional arguments:

cd ~/projects/test_package/node_modules/express
npm link

We could use this same procedure to make our own test_package available to other packages we are creating (assuming it had the proper directory structure and files, which it does not now).

While we are installing and shuffling our packages around, we should take advantage of the dedupe function.

Our packages have dependencies installed under them in the hierarchy. However, some packages may have shared dependencies. If our package directory contains two modules that each require a package called “blah”, it will be installed twice, once under “package1/node_modules/blah” and one under “package2/node_modules/blah”.

The dedupe subcommand looks for these cases and moves shared dependencies up a level, where both packages will find the single installation of the dependency.

For example, we can try to dedupe the dependencies of our packages in the express directory. We can do this in the package directory like this:

cd ~/projects/test_package/node_modules/express
npm dedupe

This will find two packages (mime and debug). The debug module is actually also a dependency of another express module dependency called “send”. This would normally be deduplicated, but there is a version conflict, so nothing is done in this instance.

Let’s say that you have deduped your packages, which moves some dependencies upwards, but then you uninstall the packages that formerly owned the dependency package. The dependency will not be removed because it is not within the packages subdirectory anymore.

In these cases, we can tell npm to “prune” packages that aren’t needed in our system. This means packages that aren’t listed in our parent package’s dependency list.

You can remove the unwanted dependencies by calling:

npm prune

This will remove the unneeded packages.

Finding Outdated Packages and Updating them

If you need to find out which packages are out of date, you can do so by typing something like this:

npm outdated

---

. . .
Package  Current  Wanted  Latest  Location
type-is    1.1.0   1.1.0   1.2.0  express > type-is
debug      0.8.0   0.8.0   0.8.1  express > send > debug

This will give you a list of packages that have more recent versions available. It will give you a chart showing what is installed, what your application requested, and how that differs from the current version.

If you want to update your packages, you should edit the version requested in the package’s package.json and then issue the update command:

npm update

Conclusion

We’ve covered some of the more common ways to use npm as a package manager. You should now have a good idea of how to acquire and manage other people’s packages for use in your own development.

In our next guide on npm, we’ll go over how to configure npm to alter its behavior, how to create packages with npm, and how to publish your packages and interact with the npm website.

<div class=“author”>By Justin Ellingwood</div>