Documentation for "npm install" unclear or incorrect

[d10r]

When doing npm help install, the second sentence in the Description section is:

If the package has a package-lock or shrinkwrap file, the installation of dependencies will be driven by that, with an npm-shrinkwrap.json taking precedence if both files exist.

I'm not sure what will be driven by that is supposed to mean. I would it interpret it this way:
If a package-lock or shrinkwrap file exists, npm installs the exact package versions described by that file. If not, it does package resolution according to the information in package.json.

That's however not what's happening.
npm install will always install the latest version of the packages allowed by package.json, overwriting package-lock.json in the process. It's not clear to me what difference it makes for the install process if there's a package-lock file in place.

Is this only me or should the documentation be changed to better reflect / explain actual behaviour?

[jkufner]

I think it is not just the documentation, the npm install is broken by design and it should be fixed.

I would expect the following behavior:

• npm install should look at package-lock.json and install the packages of the exact versions specified there. If package-lock.json is in conflict with package.json, then npm should fail with an error and do nothing (and suggest running npm update to fix the issue).

• npm update should look for the latest versions of packages defined in package.json and install or update to the latest version that matches the specified constaints. Then it should update package-lock.json to record what has been installed.

This is how Composer (PHP) works and there is no confusion around it. It is very simple and practical.

[d10r]

@jkufner I also find the behaviour npm install unfortunate and I guess this has been discussed before and is probably a controversial topic.
Thus my suggestion is to at least make sure that the documentation is correct and understandable.

Btw. the reason why I opened this issue is: I was about to open an issue in a project using node.js, where I wanted to encourage use of npm ci in order to have reproducible builds. But I failed to find documentation which explains that npm install doesn't stick to what is listed in the package-lock file.

[kyeotic]

My favorite response to this insanity comes from a comment on this SO question

Why would you expect something called package lock to lock the packages? Package lock is analogous to how, when you put any key into a door lock, the lock reshapes itself to match whatever key was put in, then opens the door. Now if you'll excuse me, I'm late for a tea party with a rabbit.

Obviously a lock file should lock the dependencies installed with the npm install command. I shouldn't have to run npm ci to use the lock file because I am not continuous integration, I am a developer. npm update should update the lockfile.