An example of application directory structure

Let's take a look at the filesystem structure of a typical Node.js Express application:

This is an Express application (we'll start using Express in Chapter 5, Your First Express Application) containing a few modules installed in the node_modules directory. One of those, Express, has its own node_modules directory containing a couple of modules.

For app.js to load models-sequelize/notes.js, it uses the following require call:

const notesModel = require('./models-sequelize/notes'); 

This is a relative module identifier, where the pathname is resolved relative to the directory containing the file making the reference.

Use the following code to do the reverse in models-sequelize/notes.js:

const app = require('../app'); 

Again, this is a relative module identifier, this time resolved relative to the subdirectory containing models-sequelize/notes.js.

Any reference to a top-level module identifier will first look in the node_modules directory shown here. This directory is populated from the dependencies listed in the package.json, as we'll see in a few pages:

const express = require('express');
const favicon = require('serve-favicon');
const logger = require('morgan');
const cookieParser = require('cookie-parser');
const bodyParser = require('body-parser');

All of these are typical modules included in an Express application. Most of them are readily visible in the screenshot shown earlier. What's loaded is the main file in the corresponding subdirectory of node_modules, for example, node_modules/express/index.js.

But the application cannot directly reference the dependencies of the Express module that are in its internal node_modules directory. The module search algorithm only moves upward in the filesystem; it does not descend into subsidiary directory trees. 

One side effect of the upward search direction is the handling of conflicting dependencies. 

Suppose two modules (modules A and B) listed a dependency on the same module (C)?  In the normal case, the two dependencies on module C could be handled by the same instance of that module. As we'll see in a few pages, npm's dependency list in package.json can use loose or precise version number references. Depending on the current version number for module C, modules A and B may, or may not, be in agreement as to which version to use. If they do not agree, npm can arrange the module installation such that both module A and B get the version of module C they depend on, without either stepping on the other. If both are agreeable with the same module C instance, only one copy will be installed, but if they disagree then npm will install two copies. The two copies will be located such that the module search algorithm will cause each module to find the correct version of module C.

Let's try a concrete example to clarify what was just said. In the screenshot earlier, you see two instances of the cookie module. We can use npm to query for all references to this module:

$ npm ls cookie
notes@0.0.0 /Users/David/chap05/notes
├─┬ cookie-parser@1.3.5
│ └── cookie@0.1.3 
└─┬ express@4.13.4
 └── cookie@0.1.5

This says the cookie-parser module depends on version 0.1.3 of cookie, while Express depends on version 0.1.5. How does npm avoid problems with these two conflicting versions?  By putting one inside the node_modules directory inside the express module. This way, when Express refers to this module, it will use the 0.1.5 instance in its own node_modules directory, while the cookie-parser module will use the 0.1.3 instance in the top-level node_modules directory.