What does 'npm i --package-lock-only' do?

Question

What does npm i --package-lock-only do exactly? The documentation is a tad shy on examples. https://docs.npmjs.com/cli/v6/configuring-npm/package-locks

I'm curious to know if I have older packages in my local node_modules folder and no package-lock.json file, will npm i --package-lock-only generate a package-lock.json according to the version in my local node_modules folder or will it generate a package-lock.json with newer package versions that is consistent with the semver ranges in the package.json that's published in the npm registry.

Pulsatory

Answer 1

It will determine versions of packages to install using package.json, and then create a package-lock.json file with its resolved versions if none exists, or overwrite an existing one.

Significantly, it does not actually install anything, which is what distinguishes it from regular npm install (or the aliased npm i).

Epperson

Does npm i create a package-lock.json if one doesn't exist (in addition to installing node_modules of course) ? – Ronnironnica

@Justin, yes npm i creates the lock file – Sensible

For people wondering why you would use this: you run this command to automatically resolve merge conflicts in your package-lock.json. See: tkdodo.eu/blog/solving-conflicts-in-package-lock-json – Discursion

Answer 2

Well, @Ben Wheeler is accurate, but there's a place to give a little background on this process.

In regular situations the package-lock is meant to set a complete dependency tree of every package and its dependencies in your application, so every developer on a different machine will have the exact same tree.

This is important because the dependencies packages might be updated with time and if every developer uses different versions, it could break your application. So every time you do npm i, if you do have a package.lock.json, it actually installs the packages from there and not from package.json.

Sometimes when developers have dependency errors they tend to delete the lock file and node_modules, which is not always the best option. Most of the time it's enough to update only the lock file to reflect the package.json with the flag --package-lock-only, and then you can run npm i again to install your packages.

The lock file should be committed to your project repo so everyone can use it to have the same packages version.

Caliper

Semantic nitpick (that might already be clear to most people): Just wanted to point out that packages are not installed from the lockfile; packaged are still installed from the registry (or cache). It'd be more accurate to say that package versions are resolved from the lockfile. The docs have an easy-to-follow example, at docs.npmjs.com/cli/v6/configuring-npm/package-locks. – Junno

chipit24 - I just read that when someone updates a package.json file manually, packages will be resolved according to package.json and the package-lock.json file will be re-written to match. Is this true? And if it is, is it the only scenario in which running npm install would not honor the package-lock.json? I'm trying to discover the best strategy for reducing risk on our production system when the ci build process runs npm i. Should it run something different? And what are the tradeoffs? I ask because you seem knowledgeable in this. – Metallurgy

First thank you for this note. package-lock.json will update when you update the package.json but it's not limited to the manually case I think, because it compare both files and if it track changes it update the lock file. I'm not sure if I understand all the mechanism behind the lock file. For example I had a unexpected behavior when I tried to update the lock file on React Native app and I ended up with deleting the file. In React I never had problems with this, so I think it must be something they do when they configuring the Native ver that is little buggy.I'm not expert with the native – Caliper

Answer 3

package-lock.json is automatically generated for any operations where npm modifies either the node_modules tree, or package.json. It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates.

This file is intended to be committed into source repositories, and serves various purposes:

• Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.
• Provide a facility for users to "time-travel" to previous states of node_modules without having to commit the directory itself.
• Facilitate greater visibility of tree changes through readable source control diffs.
• Optimize the installation process by allowing npm to skip repeated metadata resolutions for previously-installed packages.
• As of npm v7, lockfiles include enough information to gain a complete picture of the package tree, reducing the need to read package.json files, and allowing for significant performance improvements.

Reference

Fawn