Anyone who has worked with Node.js for any length of time has probably asked themselves: “Do I really need this package-lock.json?” Or even worse: “Can I just delete it?” If you’ve ever done that, let me explain why that might have been one of the worst ideas ever.
What is package-lock.json?
In short, package-lock.json is a file that holds the exact version of your Node.js dependencies. While package.json only specifies which packages you need (often with version ranges like ^ or ~), package-lock.json specifies exactly which version has been installed.
Why is this important? Because it ensures that your code uses exactly the same dependencies on every machine. Without it, an npm install on a different machine could install a different version of a module – potentially introducing bugs or incompatibilities.
In addition, package-lock.json contains metadata about each dependency, including download URLs, lockfileVersion and integrity checks. This prevents unexpected deviations and ensures stability.
|
File
|
Purpose
|
|---|---|
|
package.json
|
Defines the dependencies of a project with version ranges (e.g. ^1.2.3)
|
|
package-lock.json
|
Saves the exact installed versions to ensure consistent builds
|
A concrete example: Assuming package.json contains the dependency “lodash”: “^4.17.0”. Without package-lock.json, npm install can install different minor versions of Lodash (e.g. 4.17.20 or 4.17.21) on different computers, depending on which one is currently available. The package-lock.json, on the other hand, ensures that exactly the same version is always used.
What is yarn.lock?
The yarn.lock file fulfills the same purpose as package-lock.json, but for Yarn, an alternative package manager to npm. It ensures that all developers and CI/CD pipelines use the same dependencies by storing exact package versions.
What is pnpm-lock.yaml?
PNPM is another alternative package manager that optimizes disk space by storing and referencing dependencies only once. pnpm-lock.yaml is the equivalent of package-lock.json and yarn.lock, but optimized for PNPM’s unique storage strategy. It ensures that all packages are installed in a deterministic manner.
Differences between package-lock.json, yarn.lock and pnpm-lock.yaml
|
Feature
|
package-lock.json
|
yarn.lock
|
pnpm-lock.yaml
|
|---|---|---|---|
|
Package manager
|
npm
|
Yarn
|
PNPM
|
|
Performance advantages
|
Slower during installations
|
Faster thanks to better caching mechanisms
|
Very fast due to symlink usage
|
|
File Format
|
JSON
|
Special text format
|
YAML
|
|
Determinism
|
Stable, but occasional inconsistencies
|
Better determinism in the resolution
|
Very deterministic
|
|
Memory optimization
|
None
|
Average
|
High (Shared Store)
|
|
Integrity checks
|
Contains integrity values and lockfileVersion
|
Also contains integrity, but optimized for yarn
|
Uses dedicated checksum functions
|
So if you use Yarn, you should always commit yarn.lock, while package-lock.json is important for npm projects. If you use PNPM, you should use pnpm-lock.yaml.
Should I commit my lock file?
Yes, lock files should always be included in the Git repository. Without them, different team members or build servers can easily install different versions of dependencies, leading to hard-to-trace bugs. By committing the file, you ensure that everyone is using exactly the same dependencies.
Why is this important?
- Consistent builds: Every developer and every CI/CD pipeline installs exactly the same versions.
- Avoidance of dependency drift: Unexpected updates are prevented by flexible version ranges in package.json.
- Traceability: If bugs occur, you can see exactly which version of the dependencies was used.
Should I delete my lock file?
No! Deleting a lock file can lead to inconsistent builds and unexpected errors. If you have problems with the file, you should rather try to update it (npm install, yarn install, pnpm install or npm update) or use npm ci, yarn install –frozen-lockfile or pnpm install –frozen-lockfile to perform a clean reinstallation.
If you really have problems with outdated or inconsistent dependencies, you can do the following:
- Delete lock file: rm package-lock.json or rm yarn.lock or rm pnpm-lock.yaml
- Delete the node modules directory: rm -rf node_modules
- Reinstall: npm install, yarn install or pnpm install
But beware: This should only be done if you can cope with possible version changes.
What impact does a lock file have on security?
- Integrity checks: Each dependency in package-lock.json, yarn.lock and pnpm-lock.yaml contains an integrity checksum. This ensures that the package manager recognizes when packages have been manipulated.
- Prevention of dependency drift: Without a lock file, new (potentially insecure) versions of dependencies could slip into your project unnoticed.
Worst-case scenario: supply chain attacks
If an attacker manages to inject a malicious version of a package into a public repository, users without a lock file could automatically update to this version. This can lead to serious security issues, e.g:
- Code injection: The attacker inserts malicious code into the compromised package, which then enters your application.
- Credential theft: The compromised package may attempt to read environment variables such as API keys or database passwords.
Backdoors: An attacker could install persistent backdoors in your system.
How can you protect yourself?
- Always commit package-lock.json: This prevents npm from automatically installing a compromised version.
- Regularly run npm audit: This allows you to identify known security issues in your dependencies.
- Use npm ci in production environments: This ensures that no unexpected changes to dependencies occur.
- Use Dependabot or Renovate: These tools help you to perform updates in a secure and controlled manner.
Practical use cases
Case 1: The “Why is it working for me but not for you?” error
Your colleague pulls your latest update, runs npm install and your project crashes immediately. But it runs perfectly on your computer. What is the problem?
Possible cause: Without package-lock.json, your colleague may have received a slightly different version of a dependency package. Perhaps a bug has crept into a minor update.
Solution:
- Make sure that package-lock.json is included in the git repository.
- Your colleague should use npm ci instead of npm install (more on this in a moment).
Case 2: CI/CD pipelines that run stably
In Continuous Integration (CI) pipelines, you want to ensure that every build is exactly the same. This is where npm ci comes into play.
Why npm ci instead of npm install?
- npm ci ignores package.json and installs exactly the versions defined in package-lock.json.
- It deletes the node_modules directory before installation to ensure a really clean environment.
- It is faster because it works directly from the lock file.
So always use npm ci in CI/CD systems or if you need absolutely reproducible builds.
Conclusion
Lock files are not just “annoying” files that are constantly changing. They are critical components of a stable, secure and reproducible Node.js environment. If you work in a team or use CI/CD, you should never ignore them.
If you have any questions or your own experiences, let me know! Happy coding! 🚀
