A Beginner’s Guide to NPM

A guide to NPM commands and concepts

Originally posted here: https://blog.bitsrc.io/a-beginners-guide-to-npm-5c021d519c4c

Given Node.js’ module ecosystem, one could argue that NPM is literally the bread and butter of any Node project. In fact, one could even go as far as to say that NPM is one of the most important tools the Node.js developer have under their communal belts. After all, they use it everyday to manage the packages their projects use.

Having said that, one could also say that it’s quite sad how little developers actually know about NPM, other than it can, indeed, install packages.

So in this article, I’ll try to cover the basics of this tool, giving you a good idea of what you can eventually achieve by using it, other than the basic package management you’re most likely already using it for.

Package Management

We all know you can install packages with NPM, but what exactly does that mean? A package is basically a folder containing the code you need and you can either install it locally or globally.

Local installation

A local install means you’re literally downloading the files into your project’s folder. Inside it, you’ll find a directory you didn’t create, called “node_modules”. Because of this simple mechanics, this local folder can potentially grow quite big.

There is a good reason why this meme was born after all:

No wonder this meme was created!

That being said, normally you can just ignore the folder, and let Node.js take care of it for you.

To perform a local install all you have to do is:

$ npm install [package-name]

You can even add the --save flag, so the package name and version is saved into your package.json file. And this is important (crucial even), because when working as part of a team, you do not distribute, nor add the node_modules folder into version control system (be it GIT, SVN or whatever you’re using), instead you simply share the package.json file and let your teammates run $npm install by themselves. This is much faster and easier to maintain than sharing a whole folder which can grow to contain Gigabytes of data.

Here is how a simple package.json file looks like:

{
  "name": "Project name",
  "version": "1.0.0",
  "description": "This is a basic description",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Fernando Doglio",
  "license": "ISC",
  "dependencies": {
    "config": "^3.1.0",
    "express": "^4.17.1",
    "socket.io": "^2.2.0",
    "winston": "^3.2.1"
  }
}

Yours might change a bit, depending on which packages you’ve installed, or which fields of the file (there are many others I didn’t use in the sample above) you need.

Global installation

You can also install packages globally, which means Node.js will be able to access them from any project you might need them. The problem? Global packages aren’t added to the package.json file, which makes sense. So why would you install global packages?

One of the many great things you can do with Node.js and NPM, is build what people usually call “binaries”, which are simply scripts that can be installed globally and thus, be accessible from anywhere on your box. That means you can create command line tools and use NPM to install them!

Without having to go too far, packages such as ExpressJS (one of the most popular Web frameworks for Node.js) or mocha (a very popular testing library) also come with executable binaries you can use. For example, mocha requires you to install it both, globally and locally in order to have a CLI tool available called “mocha” and the ability to run tests on your local project.

Global packages create a symlink (or shortcut) inside a general path that you need to add to your PATH environment variable.

Classic commands with NPM

The install command is but one of the many you can use with NPM. In fact, leaving aside the almost 60 different commands (yeap, you read that right!) that I’m going to briefly cover in a second, NPM also allows you to create your own custom commands in case the built-in ones aren’t enough for you.

Here is the list of the most common commands, taken from the official documentation:

• access: Sets access level on published packages, restricting or enabling access to others aside from its author. Example: $ npm access public

• adduser: Adds a user account to the registry (by default, the registry is npm’s registry, but you can specify a custom one). Example: $ npm addUser and the user credentials (username and password) as well as their email will be entered when prompted to.

• audit: Runs a security audit on your installed dependencies, making sure no known vulnerabilities are affecting them (and by extension, your project). You can even use the flag fix to automatically fix any problems you might find during this audit.

• bin: Shows NPM’s bin folder for the current project.

• bugs: Opens the list of bugs inside a new browser window. The interesting bit about this command, is that it tries to guess the current bug tracker for the package and once it finds it, then it’ll launch a new browser window.

• cache: Although not normally used by developers, this command allows them to either clear, verify or add something to NPM’s cache. In that cache HTTP request information and extra package data is stored. Normally this is handled directly by NPM and works transparently to devs, but if you see some strange behavior, especially when switching between different packages and different versions of them, it might be a good idea to try and clear the cache (just to be on the safe side).

• ci: Pretty much the same as npm install but meant to be used in automated environments (such as a Continuous Integration process). This command is more strict than install and makes sure the installation is always clean (it automatically deletes the node_modules folder if it’s present).

• completion: Enables Tab Completion for npm and its sub commands. Read the full documentation for more details.

• config: Allows you to set, get and edit the configuration options for NPM.

• dedupe: **Attempts to reduce duplication of dependencies by traversing the dependency tree and moving duplicated entries as far up the hierarchy as possible. **This is especially useful when your application starts to grow and incorporate a growing number of modules. Using this command is definitely optional, but it will provide a considerable reduction during installation times (most useful on CI/CD environments) if you have a lot of dependencies.

• deprecate: Adds a deprecation warning on the library’s registry for a particular version (or range of versions).

• **dist-tag: **Helps mange tags for a particular package. Tags can act as version aliases to help identify versions without having to remember the numbers. For example, by default the **latest **tag is used for the last version of all libraries and you can simply run npm install library-name@latest and NPM will understand which version of the library to download.

• docs: **Just like **bugs this command attempts to guess where the official documentation for the package is, and opens that URL in a local browser.

• **doctor: **Performs a set of pre-defined checks to make sure the system where NPM is being executed from has the minimum requirements ready: the node and git commands are accessible and executable, the node_modules folders (both local and global) are writable by NPM, the registry or any custom version of it is accessible and finally, that the NPM cache exists and it’s working.

• help-search/help: Help will display the documentation page for a given term, and if no results are found, help-search will perform a full-text search on NPM’s markdown help files and display a list of relevant results.

• **hook: **Allows you to configure new NPM hooks, which in turn will notify custom URLs when changes are made to packages of interest. For example, you can get notified when a new version of ExpressJS is released by typing: $npm hook add express http://your-url.com/new-express-version-endpoint and in turn, you can do anything you like with that information (such as auto-updating your dependencies).

• init: Helps to initialize a project by asking a series of question such as name, version, author and so on. At the end a brand new package.json file is created with that information. You also have the ability to provide a custom initializer to customize the processed to your particular stack.

• install: Installs a new package. You can specify where the package is located, and its format (i.e you can provide only a name so it’ll look for it in the main registry, or the path to tarball file where you’ve downloaded the package to install). You can also specify the version to install if you don’t want the latest to be installed every-time you run this command (especially useful to automated environments, such as CI/CD).

• **ls: **Lists all the installed packages for the current project. You can make it list global packages or locally installed ones. In either case, it’ll list not only the names and versions visible in the package.json file, but it will also list their dependencies and their versions.

• outdated: Checks for outdated packages in your project. It’ll provide you with a report of the installed packages, their current version, the version your package.json file is expecting and the latest version published in the main registry.

• **owner: **Allows you to manage package owners. This is important if you’re either a library owner or maintainer, but not if you’re just limited to consuming packages.

• ping: Pings the currently configured main npm registry and tests the authentication as well. this is only useful if you’re having issues download or installing any package. And it will only help you troubleshoot part of the problem, but it’s important to have remember it nevertheless.

• prefix: Displays the current prefix, or in other words, the path to the closest folder with a package.json file inside it. You can use the -g flag and you’ll get the actual place where the global packages are installed.

• publish: Enables developers to share their modules with others publicly or privately by the use of groups and organizations.

These are the either the most common or most useful NPM commands available to you, but there are still more than 10 extra commands for you to review so I’d recommend you bookmark their documentation and make a note to go back and double check it!

Publishing my own packages

The last bit of NPM knowledge I wanted to impart on you was how easy it is to actually share your work with others. In the previous list, the very last command was the publish one, which basically allows you to do just that, but here I want to give you a bit more detail.

Preparing your project’s metadata

NPM’s registry is essentially a huge packages search engine, capable of both, hosting everything so you don’t have to and at the same time, index every bit of metadata it can get on your work, in order to help others find your modules as quickly as possible.

In other words, make sure your package.json is properly setup. These are the main points of interest for you (and others!) to start looking into sharing packages with them.

• Name: This is the most obvious and common from the list, and one that you’ve probably already setup when you created the package.json file to keep track of your dependencies. Just be mindful of it and add it in you haven’t already.

• Description: Again, a quick and easy-to-understand one. That being said here is where you want to both: describe you package so others can quickly understand what they’re getting when installing. And make sure you add as many important keywords inside the descripiption so the search engine knows how to find you quickly as well. It’s a balance between the needs of the developers trying to find your package and the engine’s trying to correctly index it first.

• Tags: This is simply put, a comma separated list of keywords. That being said, these tags are very important once you start publishing packages, because on NPM’s main site, they act as categories you can easily browse. So neglecting to add this property to your package.json prevents developers from finding your work through navigation.

• Private: Unless you’re just publishing content for you and you alone, you’ll want to set this property to false as soon as you can, otherwise no one will be able to find your modules through keyword search.

• Bugs: This make sure that if you’re hosting your content somewhere such as Github where there is public issue tracking, you set this property to the right URL. This’ll help NPM show a link and display the number of currently open issues right there on the package’s page.

• Repository: Another property that is not strictly required, but if you add it, NPM will be able to show extra information such as a link to it, activity, list of collaborators, just to name a few.

• Homepage: Like the previous one, it’ll help NPM display a separate link to this URL if present. This is especially relevant when you have your code in one URL (such as a Github repo) and a particular website dedicated to your module in another URL.

• License: This is used to display to actual license you’ve setup on your project. It’ll appear on a different and more prominent way if you add it as part of your package.json file. You can also just mention it on your readme.md, but adding it here will provide extra knowledge about your project to NPM.

By providing the metadata I mentioned above, NPM is able to showcase that data and highlight it for developers to see. Take the following example, the package page for Winston, a fantastic logging library:

Notice how many links and extra bits and details have been added thanks to the metadata added by its team.

Writing a nice documentation

This step shouldn’t, but it’s completely optional. I say shouldn’t, of course, because if you’re trying to publish a module that is meant to be used by other developers, you **need **to provide good documentation.

You can’t really expect your tool to be “trivial to use”, or “easy to understand and figure out”. The point of NPM’s registry, is to provide others with pre-made tools that’ll help them solve problems they don’t want nor have the time to solve by themselves. So avoiding to provide a simple set of instructions and explanations prevents them from actually wanting to try and use your tool.

With that being said, NPM’s main site takes a cue from Github in the sense that they also look for a file called readme.md in the root of your project’s directory. If present, they’ll turn your markdown documentation into a nice homepage as you can see in the above screenshot.

So there isn’t really any excuse when it comes to writing the basic documentation others will need, so just do it in the readme.md and you’ll have it available in two places at once.

Actually publishing your package

After coding, setting up the right amount of data into your package.json and writing a useful readme.md file, you’re ready to publish.

To perform this, you’ll have to do two things:

1. Log-in to your NPM account (assuming you’ve created one using their website) using the actual npm CLI.

2. Publish your code.

That’s it, 2 steps, and you’re done. To log-in simply type:

$ npm login

That’ll prompt you to enter your credentials, and once you’ve successfully logged in, you can type:

$ npm publish

Remember to do this from within your project’s folder, otherwise the second command will fail.

Also, remember that the name of your package will be given by the **name **property from your package.json file and not from the folder’s name (which usually tends to coincide, but doesn’t mean a thing). So if you’re having a repeated name error (which could happen given the amount of packages available in NPM), that is where you’ll have to make the change.

Conclusion

Thanks for reading and I hope that by now, you’ve manged to understand the complexity and beauty of NPM. It is not just a simple tool for you to install package, but you can do a lot more with it if you take the time to check their documentation.

Let me know down in the comments if you were aware of everything I just mentioned and if I missed something else you’re currently using NPM for, I’d love to know!

Otherwise, see you on the next one!