A comprehensive beginner’s guide to NPM

what is it? how does it work? and why it matters

Node.js has a massive ecosystem. It’s completely open-source and is used by more than 11 million developers worldwide.

What is NPM?

NPM is an acronym that stands for Node Package Manager. It is a JavaScript library registry that is accessible via the CLI. It’s the space where the cool kids go to publish their open-sourced projects, share helpful tools, and manage packages a project may use. 

NPM is no doubt popular but, still, not everyone appears to be aware of it. 

Yes. NPM’s main usage is to install packages and this article will go over the basics of getting started. You don’t need to be an advanced pro to get a project moving with the help of NPM. Rather, these tips and tricks will help speed up your workflow and give you access to a large resource pool of open-sourced packages. 

But before we begin….

What exactly is a package? and why does it need to be managed?

In short, a package is basically a folder containing all the code you need for a particular feature. It can be a pluggable module or library of scripts that do something.

That something can be anything you can dream, think, and imagine. How about a real world example?!

Cheerio.js is a fast, flexible, and lean implementation of core jQuery designed specifically for the server.

Cheerio parses markup and provides an API for traversing/manipulating the resulting data structure. It does not interpret the result as a web browser does.

Here is what a popular code snippet from the cheerio.js API looks like:

request.get('https://news.ycombinator.com/', (err, request, body) => {
  if (err) { return next(err); }
  const $ = cheerio.load(body);
  const links = [];
  $('.title a[href^="http"], a[href^="https"]').slice(1).each((index, element) => {
   links.push($(element));
  });
  res.render('api/scraping', {
   title: 'Web Scraping',
   links
  });
 });

You can find more snippets here

One thing all packages have in common is that they’re all JavaScript based. 

Projects are often created by developers tapping into the plethora of open-sourced projects for solutions that other developers have developed. Sharing code is how code communities grow and NPM is one of the reasons why JavaScript has propelled its way forward in popularity, especially among the new generation of developers.

So why does it need to be managed?

Imagine a world where you have more than a dozen compulsory packages that are used throughout your JavaScript project. Now imagine having to go source and download every single package from wherever the source developer is hosting it.

The source developer has to deal with hosting cost — and if the package download reaches a high enough volume, that cost will increase proportionately.

However, with NPM, there is no cost to hosting unlimited public packages. The cost of privacy is low enough that your weekly dose of a Starbucks venti coffee probably costs more. 

Basically, it’s free to make things free through NPM. 

It’s good to note that for NPM to work, you’ll need to go and download node.js onto your machine. 

Local installation

A local installation is basically downloading all the files you need into your project’s folder. Your packages list sits inside a json file called package.json and when the command to install is called, NPM will go to the registry and download everything stated in this list.

To install everything, use the following command in your CLI:

npm install

If you don’t already have it, a folder called node_modules will also appear in your project’s folder. Most of the time, you can just ignore the folder — but don’t delete it. Just keep it there. Node.js will take care of everything for you after that.

To install packages that aren’t already in your package.json list, you can use the following command in your CLI:

npm install [package-name-here]

When you add the --save flag at the end of the command above, it’ll also save the package name and current version into your package.json file. 

It’s also good to note that you should not add the node_modules folder as part of your version control systems like GIT or SVN. Instead, just share your package.json file. 

Keep in mind that the node_modules folder is heavy. It’s so heavy that if you’re working in a team and you’re downloading the node_modules folder without node.js to coordinate everything, it can take a very long time to push and pull code from your code versioning spaces. 

Use npm install instead to deal with all the packages you’ve accumulated over the course of your application’s creation process.

Global installation

Let’s say you’re running multiple projects that are using the same node modules. However, you have to download and store these node modules, which can take up space on your local machine.

If only you had the ability to consolidate and point its usage to a shared space…

Well, you’re in luck — a global installation does just that. 

The only thing that you need to note is that when you create global installations, the packages aren’t added to your project’s package.json file, so this is something you need to be aware of. 

To save your package in the global space, use the following command:

npm install -g [package-name-here]

And that’s basically it. The -g flag lets NPM knows that you want to install it in the global space, so it won’t appear inside your project’s node_module folder. 

Common commands guide

As you would have noticed by now, the base command for npm is basically npm add followed by the package name. 

However, there’s a little bit more to using NPM than just adding new packages. Here’s a list of common commands that are available with NPM.

Installing a package globally

This will let you install the package in the global space and make it accessible to your application from a common area. If you have it in the global space, you don’t need to install it in your local directory to make things work.

npm install [package-name-here] -g

Uninstalling a global package

Most packages are small in size but it can add up over time. To clear out some space, or conflicting modules, you can use uninstall to get rid of the downloaded package. 

npm uninstall [package-name-here] -g

Uninstalling a local package

Sometimes, conflicts in packages can happen, or you just don’t need them anywhere. Here’s how you uninstall a local package via npm.

Go to the root of your project’s folder and use the following command:

npm uninstall [package-name-here]

Search for a package

Sometimes, you’re just not sure if you’ve got a particular package or not. You can search for it using the following command:

npm search [package-name-here]

List all installed global packages

It’s not too bad if you just have a few global packages installed. However, over time, it’s easy to build up this space with more than a few dozen packages — especially if you’ve been playing and experimenting with code. 

Here is the command that will give you a list of all the globally installed packages.

npm ls -g

List all globally installed packages details

Need more details on what’s been installed? Use the following command and your CLI will print out more details about each package installed such as dependencies, versions, sources and any other information available against the package. 

npm ls -gl

List all local packages

Same idea as listing all the global packages — but at a local level. Go to the root of your project’s folder and run the following command:

npm ls

List all local packages details

This will give you more details on all the local packages installed within a particular project directory. Go to the root of your project’s folder and run the following command:

npm ls -l

Update all global packages to latest versions

Every now and then, packages get updated to fix bugs or to work properly with the latest releases of other frameworks and libraries that they might be used in.

However, updating everything individually can be a tedious task. npm comes with the ability to update everything all at once. Here’s how you do it for globally installed packages.

npm update -g

Update all local packages to latest versions

The same concept of updating all packages can also be applied to local packages. Just drop the -g tag that tells npm to target the global space. 

Be sure to go to the root of your project’s folder and run the following command:

npm update

Create and install packages with package.json

Go to the rood of your app’s directory and create a new package.json file. You can create one via the CLI using the following command:

touch package.json

Your file should look something like this:

{
 "name": "your app name"
, "version": "0.0.1"
, "private": true
, "dependencies": {
   "express": ">=2.5.0"
 , "jade": ">= 0.16.4"
 , "mongoose": ">=2.3.10"
 }
}

Or add whatever dependencies you need for your application needs. Then all you have to do is run npm install and viola! You don’t have to manually run npm install [your-package-name] for every single dependency.

And that’s basically it on how to use NPM. 

If you’re just consuming npm packages and using them for your projects, the knowledge here is enough. Most of the time, these commands will suffice and anything else sits in the realm of intermediate and power users.