package.json vs Lock Files (package-lock.json, yarn.lock, bun.lock, pnpm-lock.yaml) – What's the Difference?

Whenever you open a JavaScript or TypeScript project—whether it’s a Node.js backend, a React/Next.js frontend, or any other JS/TS project—you’ll always find a package.json file. This file contains all the project metadata, such as the name, description, version, dependencies, and other details required to run the project. Your package manager uses this file to install the necessary dependencies. This is basic knowledge for most developers unless you’re very new to JavaScript development. But we’re not here to talk about package.json today.

Today, we’re going to talk about the lock file that appears in your project. Unlike package.json, this file isn’t there at the start of a project—it only gets generated when you install packages using your package manager. The lock file varies depending on the package manager you use:

• npm install → package-lock.json
• yarn install → yarn.lock
• pnpm install → pnpm-lock.yaml
• bun install → bun.lock

For this explanation, I’ll refer to package-lock.json, but the concept applies to all lock files. They differ in name and structure, but their purpose remains the same.

Ideally, there should be only one type of lock file in a project because you should use only one package manager consistently. If multiple developers use different package managers, it can lead to dependency issues—a topic we’ll discuss later.

Why Do We Need a Lock File?

The lock file tracks all dependencies in the project. It maintains a record of the dependency tree and the exact versions of installed packages. When you install dependencies (i.e., node_modules), package-lock.json ensures that the exact same versions are installed across different environments.

Wait, Doesn’t package.json Already Track Versions?

Yes and no.

package.json contains the versions of dependencies, but these are typically version ranges, not exact versions.

For example:

"lodash": "^4.17.0"

• ^4.17.0 allows any version 4.x.x, as long as it’s not a major update.
• ~4.17.0 allows 4.17.x, but no minor or major updates.

On the other hand, package-lock.json records the exact version installed, including sub-dependencies:

"lodash": "4.17.21"

Even if package.json allows a range, package-lock.json ensures that every installation gets the same exact version.

Why Is This Important?

Without a lock file, running npm install at different times or on different machines could result in different versions being installed, leading to unexpected behavior.

Example Scenario

• Day 1: You run npm install with "lodash": "^4.17.0", and it installs 4.17.20.
• Day 2: A new patch, 4.17.21, is released. Another developer runs npm install (without a lock file), and they get the newer version.

Now, the project might behave differently for different developers due to subtle changes in dependencies.

Standardizing a Package Manager

Using a single package manager is crucial. If one developer installs dependencies using npm, a package-lock.json is created. But if another developer installs packages using yarn, a yarn.lock file is generated instead, leading to version mismatches.

More Benefits of package-lock.json

• It locks sub-dependencies, ensuring consistency across all environments.
• It speeds up installations by skipping the dependency resolution process.

Final Thoughts

In short, package-lock.json is essential for stability, consistency, and efficient dependency management in your project. Always commit it to your repository and ensure your team uses a single package manager to avoid unnecessary issues.