Chapter 3: A Beginner’s Guide to npm — the Node Package Manager

by Michael Wanyoike & Peter Dierx

To make use of these tools (or packages) in Node.js we need to be able to install and manage them in a useful way. This is where npm, the Node package manager, comes in. It installs the packages you want to use and provides a useful interface to work with them.

In this chapter, I'm going to look at the basics of working with npm. I will show you how to install packages in local and global mode, as well as delete, update and install a certain version of a package. I'll also show you how to work with package.json to manage a project's dependencies. If you're more of a video person, why not sign up for SitePoint Premium and watch our free screencast: What is npm and How Can I Use It?.

But before we can start using npm, we first have to install Node.js on our system. Let's do that now...

Installing Node.js

Head to the Node.js download page and grab the version you need. There are Windows and Mac installers available, as well as pre-compiled Linux binaries and source code. For Linux, you can also install Node via the package manager, as outlined here.

For this tutorial we are going to use v6.10.3 Stable. At the time of writing, this is the current Long Term Support (LTS) version of Node.

Let's see where node was installed and check the version.

$ which node
/usr/bin/node
$ node --version
v6.10.3

To verify that your installation was successful let's give Node's REPL a try.

$ node
> console.log('Node is running');
Node is running
> .help
.break Sometimes you get stuck, this gets you out
.clear Alias for .break
.exit  Exit the repl
.help  Show repl options
.load  Load JS from a file into the REPL session
.save  Save all evaluated commands in this REPL session to a file
> .exit

The Node.js installation worked, so we can now focus our attention on npm, which was included in the install.

$ which npm
/usr/bin/npm
$ npm --version
3.10.10

Node Packaged Modules

npm can install packages in local or global mode. In local mode it installs the package in a node_modules folder in your parent working directory. This location is owned by the current user. Global packages are installed in {prefix}/lib/node_modules/ which is owned by root (where {prefix} is usually /usr/ or /usr/local). This means you would have to use sudo to install packages globally, which could cause permission errors when resolving third-party dependencies, as well as being a security concern. Lets change that:

Changing the Location of Global Packages

Let's see what output npm config gives us.

$ npm config list
; cli configs
user-agent = "npm/3.10.10 node/v6.10.3 linux x64"

; userconfig /home/sitepoint/.npmrc
prefix = "/home/sitepoint/.node_modules_global"

; node bin location = /usr/bin/nodejs
; cwd = /home/sitepoint
; HOME = /home/sitepoint
; "npm config ls -l" to show all defaults.

This gives us information about our install. For now it's important to get the current global location.

$ npm config get prefix
/usr

This is the prefix we want to change, so as to install global packages in our home directory. To do that create a new directory in your home folder.

$ cd ~ && mkdir .node_modules_global
$ npm config set prefix=$HOME/.node_modules_global

With this simple configuration change, we have altered the location to which global Node packages are installed. This also creates a .npmrc file in our home directory.

$ npm config get prefix
/home/sitepoint/.node_modules_global
$ cat .npmrc
prefix=/home/sitepoint/.node_modules_global

We still have npm installed in a location owned by root. But because we changed our global package location we can take advantage of that. We need to install npm again, but this time in the new user-owned location. This will also install the latest version of npm.

$ npm install npm --global
└─┬ [email protected]
  ├── [email protected]
  ├── [email protected]
....
├── [email protected]
└── [email protected]

Finally, we need to add .node_modules_global/bin to our $PATH environment variable, so that we can run global packages from the command line. Do this by appending the following line to your .profile, .bash_profileor .bashrc and restarting your terminal.

export PATH="$HOME/.node_modules_global/bin:$PATH"

Now our .node_modules_global/bin will be found first and the correct version of npm will be used.

$ which npm
/home/sitepoint/.node_modules_global/bin/npm
$ npm --version
5.0.2

Installing Packages in Global Mode

At the moment we only have one package installed globally — that is the npm package itself. So let's change that and install UglifyJS (a JavaScript minification tool). We use the --global flag, but this can be abbreviated to -g.

$ npm install uglify-js --global
/home/sitepoint/.node_modules_global/bin/uglifyjs -> 
/home/sitepoint/.node_modules_global/lib/node_modules/uglify-js/bin/uglifyjs
+ [email protected]
added 4 packages in 5.836s

As you can see from the output, additional packages are installed — these are UglifyJS's dependencies.

Listing Global Packages

We can list the global packages we have installed with the npm list command.

$ npm list --global
home/sitepoint/.node_modules_global/lib
├─┬ [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
....................
└─┬ [email protected]
  ├─┬ [email protected]
  │ └── [email protected]
  └── [email protected]

The output however, is rather verbose. We can change that with the --depth=0 option.

$ npm list -g --depth=0
/home/sitepoint/.node_modules_global/lib
├── [email protected]
└── [email protected]

That's better — just the packages we have installed along with their version numbers.

Any packages installed globally will become available from the command line. For example, here's how you would use the Uglify package to minify example.js into example.min.js:

$ uglifyjs example.js -o example.min.js

Installing Packages in Local Mode

When you install packages locally, you normally do so using a package.json file. Let's go ahead and create one.

$ npm init
package name: (project)
version: (1.0.0)
description: Demo of package.json
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)

Press Enter to accept the defaults, then type yes to confirm. This will create a package.json file at the root of the project.

{
  "name": "project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo "Error: no test specified" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

The fields are hopefully pretty self-explanatory, with the exception of main and scripts. The main field is the primary entry point to your program and the scripts field lets you specify script commands that are run at various times in the lifecycle of your package. We can leave these as they are for now, but if you'd like to find out more, see the package.json documentation on npm and this article on using npm as a build tool.

Now let's try and install Underscore.

$ npm install underscore
npm notice created a lockfile as package-lock.json. You should commit this file.
npm WARN [email protected] No description
npm WARN [email protected] No repository field.

+ [email protected]
added 1 package in 0.344s

Now if we have a look in package.json we will see that a dependencies field has been added:

{
  ...
  "dependencies": {
    "underscore": "^1.8.3"
  }
}

Managing Dependencies with package.json

As you can see, Underscore v1.8.3 was installed in our project. The caret (^) at the front of the version number indicates that when installing, npm will pull in the highest version of the package it can find where the only the major version has to match (unless a package-lock.json file is present). In our case, that would be anything below v2.0.0. This method of versioning dependencies (major.minor.patch) is known as semantic versioning. You can read more about it here: Semantic Versioning: Why You Should Be Using it.

Also notice that Underscore was saved as a property of the dependencies field. This has become the default in the latest version of npm and is used for packages (like Underscore) required for the application to run. It would also be possible to save a package as a devDependency by specifying a --save-dev flag. devDependencies are packages used for development purposes, for example for running tests or transpiling code.

You can also add private: true to package.json to prevent accidental publication of private repositories as well as suppressing any warnings generated when running npm install.

By far and away the biggest reason for using package.json to specify a project's dependencies is portability. For example, when you clone someone else's code, all you have to do is run npm i in the project root and npm will resolve and fetch all of the necessary packages for you to run the app. We'll look at this in more detail later.

Before finishing this section, let's quickly check Underscore is working. Create a file called test.js in the project root and add the following:

const _ = require('underscore');
console.log(_.range(5));

Run the file using node test.js and you should see [0, 1, 2, 3, 4] output to the screen.

Uninstalling Local Packages

npm is a package manager so it must be able to remove a package. Let's assume that the current Underscore package is causing us compatibility problems. We can remove the package and install an older version, like so:

$ npm uninstall underscore
removed 2 packages in 0.107s
$ npm list
[email protected] /home/sitepoint/project
└── (empty)

Installing a Specific Version of a Package

We can now install the Underscore package in the version we want. We do that by using the @ sign to append a version number.

$ npm install [email protected]
+ [email protected]
added 1 package in 1.574s

$ npm list
[email protected] /home/sitepoint/project
└── [email protected]

Updating a Package

Let's check if there's an update for the Underscore package:

$ npm outdated
Package     Current  Wanted  Latest  Location
underscore    1.8.2   1.8.3   1.8.3  project

The Current column shows us the version that is installed locally. The Latest column tells us the latest version of the package. And the Wanted column tells us the latest version of the package we can upgrade to without breaking our existing code.

Remember the package-lock.json file from earlier? Introduced in npm v5, the purpose of this file is to ensure that the dependencies remain the same on all machines the project is installed on. It is automatically generated for any operations where npm modifies either the node_modules folder, or package.json file.

You can go ahead and try this out if you like. Delete the node_modules folder, then re-run npm i. The latest version of npm will install Underscore v1.8.2 (as this is what is specified in the package-lock.json file). Earlier versions will pull in v1.8.3 due to the rules of semantic versioning. In the past inconsistent package versions have proven a big headache for developers. This was normally solved by using an npm-shrinkwrap.json file which had to be manually created.

Now, let's assume the latest version of Underscore fixed the bug we had earlier and we want to update our package to that version.

$ npm update underscore
+ [email protected]
updated 1 package in 0.236s

$ npm list
[email protected] /home/sitepoint/project
└── [email protected]

Searching for Packages

We've used the mkdir command a couple of times in this tutorial. Is there a node package that does the same? Let's use npm search.

$ npm search mkdir
NAME      | DESCRIPTION          | AUTHOR          | DATE       | VERSION
mkdir     | Directory crea…      | =joehewitt      | 2012-04-17 | 0.0.2
fs-extra  | fs-extra conta…      | =jprichardson…  | 2017-05-04 | 3.0.1
mkdirp    | Recursively mkdir,…  | =substack       | 2015-05-14 | 0.5.1
...

There is (mkdirp). Let's install it.

$ npm install mkdirp
+ [email protected]
added 2 packages in 3.357s

Now create a file mkdir.js and copy-paste this code:

const mkdirp = require('mkdirp');
mkdirp('foo', function (err) {
  if (err) console.error(err)
  else console.log('Directory created!')
});

And run it from the terminal:

$ node mkdir.js
Directory created!

Re-installing Project Dependencies

Let's first install one more package:

$ npm install request
+ [email protected]
added 54 packages in 15.92s

Check the package.json.

"dependencies": {
  "mkdirp": "^0.5.1",
  "request": "^2.81.0",
  "underscore": "^1.8.2"
},

Note the dependencies list got updated automatically. In previous versions of npm, you would have had to execute npm install request --save to save the dependency in package.json. If you wanted to install a package without saving it in package.json, just use --no-save argument.

Let's assume you have cloned your project source code to a another machine and we want to install the dependencies. Let's delete the node_modules folder first then execute npm install

$ rm -R node-modules
$ npm list
[email protected] /home/sitepoint/project
├── UNMET DEPENDENCY mkdirp@^0.5.1
├── UNMET DEPENDENCY request@^2.81.0
└── UNMET DEPENDENCY underscore@^1.8.2

npm ERR! missing: mkdirp@^0.5.1, required by [email protected]
npm ERR! missing: request@^2.81.0, required by [email protected]
npm ERR! missing: underscore@^1.8.2, required by [email protected]

$ npm install
added 57 packages in 1.595s

If you look at your node_modules folder, you'll see that it gets recreated again. This way, you can easily share your code with others without bloating your project and source repositories with dependencies.

Managing the Cache

When npm installs a package it keeps a copy, so the next time you want to install that package, it doesn't need to hit the network. The copies are cached in the .npm directory in your home path.

$ ls ~/.npm
anonymous-cli-metrics.json  _cacache  _locks  npm  registry.npmjs.org

This directory will get cluttered with old packages over time, so it's useful to clean it up occasionally.

$ npm cache clean

You can also purge all node_module folders from your workspace if you have multiple node projects on your system you want to clean up.

find . -name "node_modules" -type d -exec rm -rf '{}' +

Aliases

As you may have noticed, there are multiple ways of running npm commands. Here is a brief list of some of the commonly used npm aliases:

• npm i <package> - install local package
• npm i -g <package> - install global package
• npm un <package> - uninstall local package
• npm up - npm update packages
• npm t - run tests
• npm ls - list installed modules
• npm ll or npm la - print additional package information while listing modules

You can also install multiple packages at once like this:

$ npm i express momemt lodash mongoose body-parser webpack

If you want to learn all common npm commands, just execute npm help for the full list. You can also learn more in our article 10 Tips and Tricks That Will Make You an npm Ninja.

Version Managers

There are a couple of tools available that allow you to manage multiple versions of Node.js on the same machine. One such tool is n. Another such tool is nvm (Node Version Manager). If this is something you're interested in, why not check out our tutorial: Install Multiple Versions of Node.js using nvm.

Conclusion

In this tutorial, I have covered the basics of working with npm. I have demonstrated how to install Node.js from the project's download page, how to alter the location of global packages (so we can avoid using sudo) and how to install packages in local and global mode. I also covered deleting, updating and installing a certain version of a package, as well as managing a project's dependencies. If you would to learn more about the new features in the latest releases, you can visit the npm Github releases page.

With version 5, npm is making huge strides into the world of front-end development. According to its COO, it's user base is changing and most of those using it are not using it to write Node at all. Rather it's becoming a tool that people use to put JavaScript together on the frontend (seriously, you can use it to install just about anything) and one which is becoming an integral part of writing modern JavaScript. Are you using npm in your projects? If not, now might be a good time to start.