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

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.

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.

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

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

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.

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.

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