holmes_00 By Simon Holmes

In this article, excerpted from the book Getting MEAN with Mongo, Express, Angular, and Node, I talk about how to manage Node.js project dependencies with nmp and a package json file.

Express is a web application framework for Node. In basic terms, an Express application is simply a Node application that happens to use Express as the framework. npm is a package manager that gets installed when you install Node, which gives you the ability to download Node modules or packages to extend the functionality of your application.

But how do these things work together, and how do you use them? A key piece to understanding this puzzle is the package.json file.


Defining packages with package.json

In every Node application there should be a file in the root folder of the application called package.json. This file can contain various metadata about a project, including the packages that it depends on to run. The following listing shows an example package.json file that you might find in the root of a new Express project.

Listing 1 Example package.json file in a new Express project



 {
   "name": "application-name",   #A
   "version": "0.0.0",           #A
   "private": true,              #A
   "scripts": {                  #A
     "start": "node ./bin/www"   #A
   },                            #A
   "dependencies": {             #B
     "express": "~4.9.0",        #B
     "body-parser": "~1.8.1",    #b
     "cookie-parser": "~1.3.3",  #B
     "morgan": "~1.3.0",         #B
     "serve-favicon": "~2.1.3",  #B
     "debug": "~2.0.0",          #B
     "jade": "~1.6.0"            #B
   }                             #B
 }

#A Various metadata defining application

#B Package dependencies needed for application to run

This is the file in its entirety, so it’s not particularly complex. There’s various metadata at the top of the file followed by the dependencies section. In this default installation of an Express project there are quite a few dependencies. Express, itself, is modular so that you can add in components or upgrade them individually.

WORKING WITH DEPENDENCY VERSIONS IN PACKAGE.JSON

Alongside the name of each dependency is the version number that the application is going to use. Notice that they’re all prefixed with a ~.

Let’s take a look at the dependency definition for Express 4.9.0. It specifies a particular version at three levels:

  • Major version (4)
  • Minor version (9)
  • Patch version (0)

Prefixing the whole version number with a ~ is like replacing the patch version with a wildcard, which means that the application will use the latest patch version available. This is considered best practice, as patches should only contain fixes that won’t have any impact on the application. But different major and minor versions could well include changes that cause problems with the application, so you want to avoid automatically using later versions of these.


Installing Node dependencies with npm

Any Node application or module can have dependencies defined in a package.json file. Installing them is really easy, and is done in the same way regardless of the application or module.

Using a terminal prompt in the same folder as the package.json file you simply need to run the following command:

$ npm install

This tells npm to install all of the dependencies listed in the package.json file. When you run it, npm will download all of the packages listed as dependencies and install them into a specific folder in the application called node_modules. Figure 1 illustrates the three key parts.

holmes_01

Figure 1 The npm modules defined in a package.json file are downloaded and installed into the application’s node_modules folder when you run the npm install terminal command.

npm will install each package into its own subfolder because each one is effectively a Node package in its own right. As such, each package also has its own package.json file defining the metadata including the specific dependencies. It’s quite common for a package to have its own node_modules folder. You don’t need to worry about manually installing all of the nested dependencies though, because this is all handled by the original npm install command.

ADDING MORE PACKAGES TO AN EXISTING PROJECT

You’re unlikely to have the full list of dependencies for a project right from the outset. It’s far more likely that you’ll start off with a few key ones that you know you’ll need, and perhaps some that you always use in your workflow.

Using npm, it’s really easy to add more packages to the application whenever you want. You simply find the name of the package you want to install and open a command prompt in the same folder as the package.json file. You then run a simple command like this:

$ npm install --save package-name

With this command, npm will download and install the new package into the node_modules folder. The --save flag tells npm to add this package to the list of dependencies in the package.json file.

UPDATING PACKAGES TO LATER VERSIONS

The only time npm downloads and reinstalls existing packages is when you’re upgrading to a new version. When you run npm install, npm will go through all of the dependencies and check the following:

  • The version defined in the package.json file
  • The latest patch version on npm (assuming you used the ~)
  • The version installed in the node_modules folder (if at all)

If your installed version is different from the definition in the package.json file, npm will download and install the version defined in package.json. Similarly, if you’re using a patch wildcard and there’s a later patch version available, npm will download and install it in place of the previous version.

Now that we’ve given you this basic look at Node, Express and npm, you can start creating your first Express project