Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 36 ยท Lockfiles and Security

Lockfiles Explained

Learn why lockfiles exist, what package-lock.json, yarn.lock and pnpm-lock.yaml record, how npm ci and frozen installs work, and how to fix merge conflicts.

Your package.json says what you accept: "express": "^4.18.0" means "any 4.x from 4.18.0 up". Run npm install today and you may get 4.21.2; run it next month and you may get 4.22.0. Two machines, two different trees, and a bug that "works on my machine". A lockfile fixes this by recording the exact version, source and integrity hash of every package in the tree, so every install reproduces the same result.

This lesson explains the three lockfile formats, how installs use them, and the habits that keep them healthy. File excerpts are read-only; the runnable examples parse and compare lockfile data with plain Node.js.

Ranges versus locks

package.json says what is allowed

Ranges ^4.18.0, ~1.2.3, >=2
Intent Written by you

Many different trees satisfy the same ranges.

1 / 2

The three formats

Manager File Format
npm package-lock.json JSON
Yarn yarn.lock Custom text (Classic), YAML-like (Berry)
pnpm pnpm-lock.yaml YAML

Never keep two lockfiles for one project. Mixed lockfiles make teammates install different trees. Pick one manager (see Corepack and the packageManager field) and delete the others.

package-lock.json

An excerpt (lockfile version 3):

JSON
{
  "name": "shop",
  "lockfileVersion": 3,
  "packages": {
    "": { "name": "shop", "dependencies": { "ms": "^2.1.0" } },
    "node_modules/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="
    }
  }
}

The keys are install paths. node_modules/a/node_modules/b means "b installed inside a", which is how npm records duplicates when two packages need different versions. dev, optional, peer and engines flags are recorded too.

yarn.lock

Classic Yarn groups every request that resolves to the same version:

TEXT
ms@^2.1.0, ms@^2.1.1:
  version "2.1.3"
  resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.3.tgz#<sha1>"
  integrity sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==

Yarn Berry (2+) uses a YAML-like layout with resolution: "ms@npm:2.1.3" and a checksum. The first line lists the descriptors (name@range) the entry satisfies.

pnpm-lock.yaml

pnpm separates what the project asked for (importers) from the resolved graph (packages and snapshots):

YAML
lockfileVersion: '9.0'
importers:
  .:
    dependencies:
      ms:
        specifier: ^2.1.0
        version: 2.1.3
packages:
  [email protected].3:
    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
snapshots:
  [email protected].3: {}

Because specifier is stored next to the resolved version, pnpm can instantly tell whether the manifest and the lockfile disagree.

Reading a lockfile in code

This example loads a miniature package-lock.json and answers questions a security reviewer asks: how many packages, which have install scripts, and who is nested (a duplicate).

Node.js Inspect a package-lock.json

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

How installs use the lockfile

Situation Behaviour
Lockfile exists and matches package.json Install exactly what it says
You add or change a dependency The manager resolves only the change and updates the lockfile
package.json and lockfile disagree npm install fixes the lockfile; npm ci stops with an error
No lockfile Full resolution, then a lockfile is written

For CI and production builds use the strict commands. They never modify the lockfile and fail on drift:

Terminal
npm ci
yarn install --immutable        # Yarn Berry  (Classic: --frozen-lockfile)
pnpm install --frozen-lockfile  # pnpm picks this automatically when CI=true

npm ci also deletes any existing node_modules first and is usually faster than install, because it skips resolution.

Detecting drift

The drift check is conceptually small: every dependency in package.json must have a locked version that satisfies its range. Here is a stand-in with a tiny range matcher for ^, ~ and exact versions.

Node.js Stand-in: does the lockfile still satisfy package.json?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

If npm ci shows this kind of message in your CI, the fix is always the same: run npm install locally, commit the updated lockfile, push again.

Good habits

  • Commit the lockfile for applications and for repositories that run CI. Library authors commit it too (it makes their CI reproducible), but consumers of the library never see it, because lockfiles are not published.
  • Review lockfile diffs in pull requests. A change in resolved hosts or in integrity without a version bump deserves a question.
  • Do not edit by hand. Regenerate with the tool.
  • Update on purpose: npm update, yarn up, pnpm update change versions within ranges; npm install pkg@latest changes the range itself.
  • Keep lockfileVersion consistent across the team by using the same manager version (Corepack, covered later).

Fixing merge conflicts

Never merge a lockfile by hand. Resolve package.json first, then let the manager rebuild:

Terminal
git checkout --theirs package-lock.json   # or --ours: take either version
npm install                               # re-resolves and fixes the file
git add package-lock.json

pnpm and Yarn Berry can also resolve lockfile conflicts automatically during install when the markers are present.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main purpose of a lockfile?

    Ranges allow many trees; the lockfile pins one, so every machine and CI run gets the same packages.
  2. 2. Which command fails instead of changing the lockfile when it disagrees with package.json?

    npm ci installs strictly from the lockfile and errors on drift. Yarn and pnpm have --immutable and --frozen-lockfile.
  3. 3. What does the key node_modules/express/node_modules/ms in package-lock.json mean?

    Keys are install paths. A nested path records a package placed inside another package's node_modules.
  4. 4. How should you resolve a merge conflict in a lockfile?

    The lockfile is generated data. Fix the manifest and let the tool rebuild a consistent lockfile.

Summary

  • package.json holds ranges; the lockfile holds the exact resolved tree with hashes.
  • npm uses package-lock.json, Yarn yarn.lock, pnpm pnpm-lock.yaml. Use one per project and commit it.
  • Use npm ci, yarn install --immutable or pnpm install --frozen-lockfile in CI.
  • Drift means the manifest and lockfile disagree; fix it by installing locally and committing.
  • Review lockfile diffs and never hand-edit them.

Next: npm audit and Vulnerabilities