liveBook · Manning

Node_modules

As explained in Secrets of the JavaScript Ninja, Third Edition

The conventional directory in a Node.js project that contains installed JavaScript packages.

A Node.js project typically keeps installed JavaScript packages in a node_modules directory. Run npm install, and npm downloads the requested package plus its dependencies into a dependency tree. This lets modules import packages by name rather than by a complete file path. section 3.2 section 3.2.1

Not every import searches node_modules. An import may name a core Node.js API, use a relative path such as ./ or ../, or start with a package name. That last form is a bare specifier. For it, Node.js checks node_modules beside the importing module, then in successive parent directories, stopping at the file-system root. After finding the package, it resolves the entry point using package.json: exports takes precedence; without exports, a specified subpath is used, or main supplies the package entry point. section 3.2.2

node_modules/
  dep1/
    node_modules/
      lodash/ # contains lodash@3
  dep2/
    node_modules/
      lodash/ # contains lodash@4

Nested node_modules directories let two dependencies use different versions of the same package: each finds the nearest copy when it imports lodash. section 3.2.2

Install and import a package

Run npm install express@5, then use import express from "express" in an .mjs file. npm installs the dependency tree; Node.js resolves the bare specifier to the installed package. section 3.2.1 section 3.2.2

Usually, commit package.json and package-lock.json rather than node_modules. package.json records top-level dependencies and permits version ranges; the lockfile records exact versions so npm install can recreate the tree. Direct edits inside node_modules are fragile: they are not checked into version control and npm may overwrite them. For a temporary dependency fix, patch-package can save an edit as a version-controlled patch. section 3.2.3 section 3.2.4

The directory-based lookup is Node.js’s default, not an absolute requirement. Yarn and pnpm offer Plug’n’Play modes that resolve dependencies from a central cache instead; tooling that expects node_modules may need attention. section 3.2.2

How Secrets of the JavaScript Ninja, Third Edition covers it

How deep it goes
Explains directory search, nested package versions, and entry-point precedence, while deferring the details of exports mappings.
Examples
Uses an Express install and import, plus a nested directory tree containing two lodash versions.
What it assumes
Assumes familiarity with JavaScript code while introducing npm installation and package-name resolution through a runnable example.
What you can do after
Diagnose/debug with it by tracing where a package-name import resolves and why different dependencies may load different versions.
How it connects
Connects npm installation and bare specifiers to package.json, package-lock.json, dependency versioning, and Plug’n’Play resolution.

Also explained in

Compare how 3 books explain node_modules →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Secrets of the JavaScript Ninja, Third Edition. The section links point to the parts of the book it draws on.