Now that node.js LTS is change to v16 many team members and even the main cloud providers have not upgraded yet and are still on v12 or v14. Node.js 14 comes with npm version 6 now we are on version 8. The teams having problem with someone messing up the git repo updating npm package json lock version 1 to 2! Let’s discuss how not to be that person!

What is package-lock.json

So you have a file called package.js that you probably know about it: one of the main things package.js does is that it keeps track of your main dependencies of the project. But these dependencies are also dependent on other libraries and they in their turn those are dependent on others. That is where package-lock.json comes to the picture! The package-lock.json keeps track of the exact version of decencies (including sub dependencies of packages you defined in package.js). Think of it as an snapshot of all packages that you have when you run npm install!

The thing is npm install (or npm i) can update the package-lock.json, for example if you have a dependency in package.json like “somePackage”: “^1.0.0”, as soon as somePackage is updated to v1.1.0 running npm install is going to update your package-lock.json with the newer version of somePackage and also all its dependencies.

In some cases you don’t want the packages to be updated (for example in case of CI/CD pipelines -workflows-) you want the exact package-lock.json unchanged so you do not face an unexpected behavior. you should run:

npm ci

“ci” stands for “continuous integration.

Other case you can run command above is when you use a git submodule and you don’t want to change a thing in the submodule as you are not maintaining it.

How to stay on version 1

The version of package-lock.json generated on your machine depend the version of npm you are using. First lets see which version of package-lock.json associates with which version of npm :

  • v1 => npm v5 and v6.
  • v2: => npm v7&v8, which is backwards compatible to v1 lockfiles.
  • v3: => npm v7&v8 without backwards compatibility

So, right now lots of code are still on version 1 and if you are working with a team and you happen to update your node js, as soon as you run npm install you upgrade the whole package-lock.json to version 2 and then you commit it with your code (that will be totally irrelevant to your commit) and since people are still on nmp 6, they get this warning:

npm WARN read-shrinkwrap This version of npm is compatible with [email protected], but package-lock.json was generated for [email protected] I’ll try to do my best with it!

So they get upset! (And like any productive programmer they go through commits to find you out! You know the rest of story )

So before upgrading to npm 8 and package-lock.json 2 please talk to your team and make sure everybody knows what is happening, and also make a pull request just for that.

But maybe you just installed NodeJS 16 and you are stuck with npm version 8 to fix that problem please run :

npm install -g npm@6.14.15
Code language: CSS (css)

on mac (and linux) you run below first, if line above was not sufficient:

rm /usr/local/bin/npm && ln -s ~/.npm-packages/bin/npm /usr/local/bin/npm
Code language: JavaScript (javascript)

And when you decide to go package-lock.json version 2, run:

npm install -g npm@latest
Code language: CSS (css)

Older node version with lockfile version 2

If you happen to update the lockfile version to 2 and have a machine or pipeline agent that has older node (thus older npm version) , you are going to face one of these errors:

in case of npm ci

fsevents not accessible from jest-haste-map

and in case of npm install you face

This version of npm is compatible with [email protected], but package-lock.json was generated for [email protected]

In case above you either downgrade your npm and make the package.lock.json with lockfile version to 1 (just run npm i and push the lock file ) or you upgrade the npm version of the machine that is generating the error to node 16 or newer ( ex. github action )

- uses: actions/[email protected] with: node-version: 16 cache: 'npm'
Code language: Bash (bash)

Recommended reads :


Leave a Reply

Your email address will not be published.