Contents
  1. What npm Is
  2. What node_modules Is
  3. What package.json Is
  4. How Modules Work Inside Node.js
  5. Why node_modules Must Not Be Committed to Version Control
  6. What to Do Now
Contents
  1. What npm Is
  2. What node_modules Is
  3. What package.json Is
  4. How Modules Work Inside Node.js
  5. Why node_modules Must Not Be Committed to Version Control
  6. What to Do Now
← All posts

Understanding node_modules and npm

Every Node.js project has a node_modules folder and a package.json. Understanding what these are and how npm manages them is foundational to working in the JavaScript ecosystem.

Authored By: Sthitadhee August 20, 2022 · Updated October 28, 2025 2 min read · 518 words · high confidence

Every Node.js project contains a node_modules folder and a package.json file. Understanding what these are, how they relate to each other, and how npm manages them is foundational to working in the JavaScript ecosystem.

What npm Is

npm is the official package manager for Node.js. It simplifies package installation, version management, and dependency tracking. When you need an external library in your project, whether a web framework, a utility, or a testing tool, npm is what installs it, records it, and allows any other developer to reproduce the same setup.

What node_modules Is

The node_modules folder is a directory in Node.js projects that stores third-party libraries and dependencies. When you install a package using npm, it downloads the package along with its own dependencies and saves them in the node_modules folder.

This folder is generated entirely from the instructions in package.json. It is not something you write or manage by hand.

What package.json Is

The package.json file is the cornerstone of your project’s interaction with npm. It is where you define all the details about your project, including the list of dependencies, devDependencies and peerDependencies.

There are three distinct dependency types worth understanding clearly.

dependencies are packages that your application needs to run in production. When you run npm install in your project directory, these packages are installed automatically.

devDependencies are packages that are only needed during development. They are not required to run your application in production. Testing frameworks such as Jest, or build tools such as webpack, belong here.

peerDependencies indicate that your package expects the consuming project to provide a specific package. This is relevant primarily when authoring libraries rather than applications.

A minimal package.json reflecting these three types:

{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.17.1"
  },
  "devDependencies": {
    "jest": "^27.0.0"
  },
  "peerDependencies": {
    "react": "^17.0.0"
  }
}

How Modules Work Inside Node.js

In Node.js, there are three types of modules: core modules, which are built into Node.js itself such as fs, http and path; local modules, which are files you write yourself; and third-party modules, which are installed from npm.

A module is any file or directory in the node_modules directory that can be loaded by the Node.js require() or import syntax. When you write require('express'), Node.js looks inside node_modules for a folder named express and loads it.

Why node_modules Must Not Be Committed to Version Control

You do not need to track automatically generated files like node_modules, which are the dependencies listed in your project’s package.json. Running npm install will create or update node_modules. There is no reason for these packages to be in version control, since npm can manage them for you.

The correct approach is to add node_modules to your .gitignore file and allow any developer cloning the project to run npm install to generate the folder locally. The package.json file is what gets committed, as it is the authoritative record of what the project depends on.

What to Do Now

Create a blank project and observe this relationship directly:

mkdir npm-test && cd npm-test
npm init -y
npm install express

Inspect the package.json file that was generated. Open the node_modules folder and observe that it contains not only express but also all the packages that express itself depends on. Then delete node_modules entirely and run npm install again. The folder is fully restored from package.json alone.

That is the contract npm enforces: package.json defines what the project needs, node_modules is the generated result, and any environment can reproduce that result with a single command.

← All posts