package-lock.json: Your Dependency Blueprint

WHY IT EXISTS: To solve the problem of "it works on my machine." Your package.json file often uses semantic versioning ranges (like "^4.17.1"), which allows for minor updates. This means two developers running npm install on different days could get different versions of a sub-dependency, leading to hard-to-trace bugs. The lock file ensures deterministic, repeatable builds for everyone.

THE MENTAL MODEL: Think of package.json as a shopping list ("get me some version of Express, around v4") and package-lock.json as the exact, itemized receipt. The receipt records the specific brand, size, and price of every single item you bought, including the ingredients used to make them. It guarantees you can go back to the store and buy the exact same cart of goods again.

HOW IT WORKS: When you run npm install, npm resolves the full dependency tree based on the ranges in package.json. It then creates a snapshot of every single package installed—your direct dependencies and all their dependencies' dependencies. This snapshot records the exact version, the resolved download URL, and an integrity hash for each package. Subsequent npm install commands will use this lock file to rebuild the exact same node_modules folder, ignoring the ranges in package.json.

WHEN TO USE IT: Always commit package-lock.json to your version control (like Git) for applications. This is critical for ensuring consistency across developer machines and in your Continuous Integration (CI) environments. In CI, you should use the npm ci command, which performs a clean install strictly based on the lock file for faster, more reliable builds.

WHEN NOT TO USE IT: You should almost always use and commit it. Historically, there was debate about whether to commit it for reusable libraries, but modern best practice is to commit it even for libraries to ensure a consistent development and testing environment for all contributors. The end-user of your library will generate their own lock file that includes your library.

ONE CANONICAL EXAMPLE: A developer runs npm install express. Their package.json gets a new line: "express": "^4.17.1". At the same time, package-lock.json is created or updated, recording not just Express version 4.17.1 but the exact versions of all its 30+ sub-dependencies (like accepts@1.3.7, body-parser@1.19.0, etc.). When a teammate pulls the code and runs npm install, they get the exact same versions, even if express@4.18.0 has since been released.