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.

Answer 1

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.

Answer 2

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).