What is the relationship between the node_modules directory and package.json?

Question

Is the structure of dependencies in node_modules simply a mirror of the dependency tree structure found in package.json? Or does performing npm install download what is in package.json and organize node_modules in some special way?

Answer 1

Ideally package.json will correspond to node_modules. Running npm install (with no arguments) will install all the packages described in package.json into node_modules, but running npm install somepackage won't modify package.json unless you use the --save option.

You can also use npm list to check if your node_modules and package.json are in sync. Packages in package.json that aren't in node_modules are tagged UNMET DEPENDENCY, whereas packages in node_modules but not in package.json are tagged extraneous.

Also note that the root package.json doesn't contain the full dependency tree; it only contains the list of direct dependencies. Dependencies of dependencies are listed in the package.json files of the dependencies themselves, recursively.