Share

The Basics: Getting started with npm

Up and running with the primary tool for the world's largest module ecosystem

Today, npm is a cornerstone of modern web development, whether used exclusively with Node.js as a package manager or as a build tool for the front end.

Understanding npm as a tool —particularly the core concepts— can be difficult for beginners. As such, we've written up this guide for getting a grasp on npm, especially for those who are entirely new to Node.js, npm, and the surrounding ecosystem.

This is a series, based on one of the most featured whitepapers we have done by developers in the Node.js ecosystem. If you are interested in the complete guide, you can get it through this link.

The 2022 guide will include this, which we will be releasing by units of knowledge every Thursday in the following weeks. Today you are in part 1 of the guide:

1. The Essential npm Commands

   • Using npm init to initialize a project
   • Using npm init --yes to instantly initialize a project
   • Install modules with npm install
   • Install modules and save them to your package.json as a dependency
   • Install modules and save them to your package.json as a developer dependency
   • Install modules globally on your system

2. The Basics of package.json

   2.1. Identifying Metadata Inside package.json

   • The name property
   • The version property
   • The license property
   • The descriptionproperty
   • The keywords property

   2.2. functional metadata inside package.json

   • The main property
   • The repository property
   • The script property
   • The dependencies property
   • The devdependencies property

3. Understanding the different types of dependencies and other host Specs inside package.json

   • PeerDependencies
   • PeerDependenciesMeta
   • OptionalDependencies
   • BundledDependencies
   • engines
   • os
   • cpu

The Essential npm Commands

When using npm, you're most likely using the command-line tool for most of your interactions. As such, here's a detailed rundown of the commands you'll encounter and need to use most frequently.

Using npm init to Initialize a Project

The npm init command is a step-by-step tool to build out the scaffolding for your project. It will prompt for input on a few aspects in the following order:

• The project's name: Defaults to the containing directory name.
• The project's initial version: 1.0.0 by default.
• The project's description: An overview of what it is and why you're doing the project.
• The project's entry point: Meaning the main file is to be executed when run.
• The project's test command: To trigger testing with something like Standard.
• The project's git repository: Where the source code can be found.
• The project's keywords: Tags related to the project.
• The project's license: This defaults to ISC. Most open-source Node.js projects are MIT.

It's worth noting that if you're content with the suggestion that the npm init command provides next to the prompt, you can hit or keys to accept it and move on to the following prompt.

Once you run through the npm init steps above, a package.json file will be generated and placed in the current directory. If you run it inside a directory that's not exclusively for your project, don't worry! It won't do anything other than creating a package.json file.

You can move it to a directory that's dedicated to your project, or you can create an entirely new one in such directory.

$ npm init # This will trigger the initialization

Using npm init --yes to Instantly Initialize a Project

If you want to get on to building your project and don't want to spend the (albeit brief) time answering the prompts that come from npm init, you can use the --yes (or -y) flag on the npm init command to populate all options with the default values automatically.

Note: You can configure what these default values are with the npm configuration commands, which we'll cover in the blogpost "Automating npm init Just a Bit More." soon on our blog

$ npm init --yes # This will trigger automatically populated initialization

Install Modules with npm install

Installing modules from the npm registry is one of the most basic things you should learn to do when getting started with npm. As you dive deeper, you'll begin to learn some variations on installing modules, but here's the very core of what you need to know to install a standalone module into the current directory:

$ npm install <module> 

In the above command, you'd replace with the name of the module you want to install. For example, if you're going to install Express (the most commonly used and most well known Node.js web framework), you could run the following command:

$ npm install express

The above instruction will install the express module into ./node_modules in the current directory and add it as a dependency inside the package.json file. Whenever you install a module from npm, it will be installed into the node_modules directory.

In addition to triggering an install of a single module, you can install all modules listed as dependencies and devDependencies in the package.json in the current directory. To do so, you'll simply need to run the command itself:

$ npm install

Once you run this, npm will begin installing all of the current project's dependencies.

As an aside, one thing to note is an alias for npm install that you may see in the wild when working with modules from the ecosystem. The alias is npm i, i takes the place of install.

This seemingly minor alias is a small gotcha for beginners to the Node.js and npm ecosystems. There's no standardized, single way module creators and maintainers will instruct how to install their module.

Usage:

$ npm install <module> # Where <module> is the name of the module  you want to install  
$ npm i <module> # Where <module> is the name of the module you  want to install - using the i alias for installation

Install Modules and Save them to your package.json as a Dependency

As with npm init, the npm install command has a flag or two that you'll find helpful in your workflow — it'll save you time and effort concerning your project's package.json file.

Before npm 5, when you ran npm install to install a module, it was only added to the node_modules directory. Thus, if you want to add it to the project's dependencies in the package.json, you must add the optional flag --save (or -S) to the command. Nowadays, since this is the default behavior, no flag is needed (although it's kept for compatibility purposes); however, if for some reason you want to go back to the old usage (i.e., install only to the node_modules folder but not add it to the package.json dependencies section) the --no-save flag is what you're looking for.

Usage:

$ npm install <module> --save # Where <module> is the name of the  module you want to install - Kept for compatibility 
$ npm install <module> --no-save # Where <module> is the name of the  module you want to install - To avoid adding it as a dependency

Install modules and save them to your package.json as a developer dependency

There's a flag that is nearly an exact duplicate, in terms of functionality, of the old --save flag when installing a module: --save-dev (or -D). There are a few key differences between the two: instead of installing and adding the module to package.json as an entry in dependencies, it will save it as an entry in the devDependencies.

The semantic difference here is that dependencies are used in production — whatever your project would entail. On the other hand, devDependencies are a collection of the dependencies used during the development of your application: the modules that you need to use to build it but don't need when it's running. This could include testing tools, a local server to speed up your development, and more.

Usage:

$ npm install <module> --save-dev # Where <module> is the name of 
the  module you want to install

Install modules globally on your system

The final and most common flags for npm install that you should know are those used to install a module globally on your system.

Global modules can be beneficial. There are numerous tools, utilities, and more for development and general usage that you can install and set available for all the projects inside your environment.

To install a module from npm in such a way, you'll simply need to use the -global(or -g)flag when running the install command to have it installed globally rather than locally (restricted to the current directory).

Note: One caveat with global modules is that npm will install them to a system directory, not a local one. With this as the default, you'll typically need to authenticate as a privileged user on your system to install global modules. You should change the default installation location from a system directory to a user directory as a best practice.

If you'd like to learn to do this, take a peek at "Tips and Tricks: Working with npm, " which we will soon release on our channels.

Usage:

$ npm install <module> --global # Where <module> is the name of  the module you want to install globally```  
$ npm install <module> -g # Where <module> is the name of the  module you want to install globally, using the -g alias

---

Remember that you can now monitor your applications and take your Node.js journey to a professional level with N|Solid.

• To get the best out of Node.js and low-cost observability, start a free trial of N|Solid.

• If you have any questions, please feel free to contact us at info@nodesource.com or through this form.

• And if you want to find out about our latest content and product releases, these are the channels to keep up to date with NodeSource:

  • • Nodesource's Twitter
  • • Nodesource's LinkedIn