Skip to main content

FAQ for lockfiles

Some questions and answers for lockfiles

André Seiji

Working with JavaScript/TypeScript often involves dealing with lockfiles such as package-lock.json, yarn.lock, or pnpm-lock.yaml.

This FAQ draws from my experience working primarily with npm-based projects. While I'm not an expert, I've gathered some insights over the years.

What is a lockfile for? #

A lockfile precisely controls and records the versions of packages and their dependencies in a project. This guarantees consistency and reproducibility across different installations and environments, preventing discrepancies in dependency versions across local development setups and cloud environments.

Should I commit the lockfile? #

Yes, committing the lockfile is important. It ensures every installation results in the same node_modules structure, facilitating consistent builds and mitigating "works on my machine" issues. Committing the lockfile also speeds up npm install, allows for easier review of dependency changes, and assists in identifying insecure dependencies through npm audit.

Why can package-lock.json change without modifications to package.json? #

Running npm install may update some dependencies within the version ranges specified in package.json, reflected in changes to package-lock.json. To better understand this, it's important to know about semantic versioning and how package.json interprets version ranges.

How does the package manager update the dependencies based on my package.json? #

If you ever wondered what the ˆ or ~ before a version means - as my younger self once did - it dictates how updates to dependencies are handled:

  • Patch releases: 1.0 or 1.0.x or ~1.0.4
  • Minor releases: 1 or 1.x or ^1.0.4
  • Major releases: * or x

A simple example would be:

  1. You have in the package.json dependencies "some-lib": "~1.0.1".
  2. A new patch version of some-lib is published; now versions 1.0.0, 1.0.1, and 1.0.2 are available on npm.
  3. You run npm install, and in the dependency resolution, it is possible to update to 1.0.2.
  4. some-lib at version 1.0.2 will be installed in node_modules, and the lockfile will be updated accordingly.

Using npm's SemVer Calculator can help visualize which versions of a package are allowed under different version ranges.

What does a change in lockfileVersion indicate? #

A change in lockfileVersion typically occurs when npm install is executed with a different version of npm, reflecting changes in how dependencies are resolved or structured in the lockfile. Refer to the npm documentation for more on lockfileVersion.

How can I ensure my CI build has consistent dependencies? #

To guarantee dependency consistency in CI environments, use the following installation commands that respect the lockfile:

  1. Use the correct versions of Node and npm for your project.
  2. Use one of the following installation commands that respect the lockfile:
# npm
npm ci

# yarn
yarn --frozen-lockfile

# pnpm
pnpm install --frozen-lockfile

This will ensure the build is using the lockfile, and the dependencies should be consistent.

If your question isn't listed #

Consult the official documentation for more in-depth guidance:

You can also use your favorite AI tool to ask about it, but always cross-reference with official sources.

Closing Note #

I recently came across JSR, a new package registry with native TypeScript support. It seems interesting, but I will have to test it myself to have an opinion.