Since release of node.js LTS v16 (and npm 8), many team members endup in different type of conflicts in lockfileVersion of their package-lock.json. Here I answer a few common questions about lockfileVersion and try to help you find best solution for your problem about package-lock.json and lockfileVersion.
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.
npm ci
Due to emerging tools like GitHub dependabot, as a developer you don’t really want to keep upgrading the packages manually each time you want to commit something. Tools like dependabot keep updting your dependencies for you for your project is always in a good shape.
This is also the case for automations like CI/CD pipelines/workflows. With npm ci you can keep the package-lock.json unchanged when while you are installing your dependencies. This guarantees that you do not face an unexpected behavior as result of some dependency suddenly gets upgraded. All you need to do is instead of npm install you run:
npm ci “ci” stands for “continuous integration, and it was intended for pipelines but I recommend to use it even on your dev environments.
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.
Which npm version is compatible with lockfileVersion 2?
Lockfiles generated by npm v7+ will contain lockfileVersion: 2 : The version of package-lock.json generated on your machine depend the version of npm you are using. Lets see which version of package-lock.json associates with which version of npm :
- lockfileVersion: 1 => npm v6 and earlier.
- lockfileVersion: 2 => npm v7+, which is backwards compatible to v1 lockfiles.
- lockfileVersion: 3 => npm v7+ without backwards compatibility
Handle npm WARN read-shrinkwrap error
Some legacy code bases 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!
To solve this you basically have 2 options:
- every one and entire of your tool chain should upgrade the node version (recommended )
- you downgrade your npm (or even node)
Upgrade to lockfileVersion: 2
If you want to go with he first option and upgrade your node to LTS (16 or 18 ), in result your npm version 8 or 9 and package-lock.json 2, please talk to your team and make sure everybody knows what is happening, and also upgrade your tool chain including dev containers, workflows (pipelines).
Stay on lockfileVersion: 1
option 1: Switch to older version of NodeJS that matched your project (recomanded)
If you need to downgrade your node to match a project you don’t need to go trough installing and uninstalling process. There is a tool called nvm (node version manager) that allows you to quickly install and use different versions of node via the command line.
Then you can use nvm cli like this to switch to your favorite version :
nvm use 14Code language: PHP (php)You can also use this tool to install different versions of NodeJS. Here you can learn how to install nvm . But here is the easy way :
# install nvm on windows
choco install nvm
# install nvm on mac OS
brew install nvm
# install nvm debian / ubuntu
curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash
#(you need to logout and login or run source ~/.bashrc )
Code language: Bash (bash)option 2: use higher version node but downgrade npm
In some cases you want to keep using the latest NodeJS but you want to keep the lockfileVersion, in that case you can downgrade your npm version:
npm install -g npm@6.14.18Code 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/npmCode language: JavaScript (javascript)And when you decide to go package-lock.json version 2, run:
npm install -g npm@latestCode 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 lockfileVers[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 matching node version. Here is an example of github workflow pipeline with specific version
- uses: actions/[email protected]
with:
node-version: 18
cache: 'npm'
Code language: Bash (bash)for other tools please use nvm as instructed above.
Leave a Reply