node_modules, package-lock.json and .gitignore

Every time you run npm install, npm creates or updates two things: the node_modules directory and the package-lock.json file. Understanding what these contain, how they relate to each other, and why one must never be committed to Git while the other always should be — is essential knowledge for working on any MERN project alone or in a team. Mishandling these files is the single most common source of “works on my machine” bugs in Node.js projects.

node_modules — What Is Inside? #

server/node_modules/
├── express/               ← Express itself
│   ├── index.js
│   └── package.json
├── accepts/               ← dependency of Express (you did not install this)
├── body-parser/           ← dependency of Express
├── debug/                 ← dependency of a dependency of Express
├── mongoose/              ← Mongoose itself
│   ├── lib/
│   └── package.json
├── ...                    ← 100s of transitive dependencies
└── .bin/
    ├── nodemon            ← CLI tools installed as executables
    └── jest

Running "npm install express" actually installs:
  express (1 package you asked for)
  + ~50 transitive dependencies (express's dependencies and their dependencies)

A typical MERN server project with ~10 direct dependencies
will have ~300-500 packages in node_modules totalling 50-150 MB

package-lock.json — Reproducible Installs #

While package.json specifies version ranges (e.g. ^4.18.2), package-lock.json records the exact version that was actually installed for every package — including all transitive dependencies. This guarantees that npm install produces byte-for-byte identical node_modules on every machine and in every CI environment.

// package-lock.json — a snapshot of exact resolved versions
{
  "name": "mern-blog-server",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "mern-blog-server",
      "dependencies": { "express": "^4.18.2" }
    },
    "node_modules/express": {
      "version": "4.18.3",
      "resolved": "https://registry.npmjs.org/express/-/express-4.18.3.tgz",
      "integrity": "sha512-...",
      "dependencies": {
        "accepts": "~1.3.8",
        "body-parser": "1.20.2"
      }
    },
    "node_modules/body-parser": {
      "version": "1.20.2"
    }
  }
}

npm install vs npm ci #

The Complete MERN .gitignore #

# ── Root .gitignore for a MERN monorepo ──────────────────────────────────────

# ── Dependencies — NEVER commit these ────────────────────────────────────────
node_modules/
**/node_modules/

# ── Environment variables — contain secrets ───────────────────────────────────
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

# ── Build output ──────────────────────────────────────────────────────────────
dist/
build/
client/dist/

# ── Logs ──────────────────────────────────────────────────────────────────────
logs/
*.log
npm-debug.log*
yarn-debug.log*

# ── Testing ───────────────────────────────────────────────────────────────────
coverage/
.nyc_output/

# ── OS files ──────────────────────────────────────────────────────────────────
.DS_Store
Thumbs.db
desktop.ini

# ── Editor files ──────────────────────────────────────────────────────────────
.vscode/settings.json    ← only if you do NOT want to share editor settings
# Note: .vscode/extensions.json and .vscode/launch.json are worth committing
*.swp
*.swo

# ── Uploads directory (user-generated content) ────────────────────────────────
server/uploads/*
!server/uploads/.gitkeep   ← keep the directory itself but not its contents

Files You SHOULD Commit #

Common Mistakes #

Mistake 1 — Accidentally committing node_modules #

❌ Wrong — running git add . before creating .gitignore:

git init
git add .   # adds ALL files including node_modules — hundreds of thousands of files!

✅ Correct — always create .gitignore before the first git add. If node_modules is already tracked, remove it from Git history:

# Remove node_modules from tracking (keeps local copy)
echo "node_modules/" >> .gitignore
git rm -r --cached node_modules
git commit -m "remove node_modules from tracking"

Mistake 2 — Deleting package-lock.json #

❌ Wrong — deleting the lock file because it “causes conflicts”:

Without package-lock.json:
  Developer A installs express → gets 4.18.3
  Developer B installs express → gets 4.18.4 (released next day)
  CI server installs express   → gets 4.19.0 (released next week)
  → Three different versions in production — unpredictable behaviour

✅ Correct — commit package-lock.json and resolve merge conflicts in it properly. The lock file is your guarantee of consistent installs.

Mistake 3 — Committing the .env file #

❌ Wrong — .env containing real credentials committed to a public repo:

JWT_SECRET=supersecret123
MONGODB_URI=mongodb+srv://admin:realpassword@cluster.mongodb.net/prod
# Now public on GitHub — database can be accessed by anyone, forever
# (Git history preserves it even if you delete the file in a later commit)

✅ Correct — add .env to .gitignore before creating it. Provide a .env.example with placeholder values instead. If you already committed it, rotate all exposed credentials immediately.

Quick Reference #