Updating a package when you’re using NPM Shrinkwrap.md

npm shrinkwrap is useful, but maddening (once it's in place and you want to update a package).

Say you've got a package.json with module ember-cli as a devDependency currently at version 1.13.1. And you have an npm-shrinkwrap.json file too, generated with the --dev flag.

If you change the version of ember-cli to, say, 1.13.8 in package.json and run npm install, nothing will happen.

If you do that and manually change references in the shrinkwrap file, you will still have trouble (as nested dependencies may now be incorrect).

So what do we actually do?

The minimal effort option — not entirely sure if it works

1. Run npm install with options just like this: npm install --save-dev --save-exact [email protected]

2. See if that correctly updated both npm-shrinkwrap.json and package.json. ¯\_(ツ)_/¯

3. You will now probably have to run npm shrinkwrap --dev. If you see errors, this means people have been updating package.json without keeping the shrinkwrap file up to date. We’d shame them, but honestly npm should probably do this for you…

Consistent but initially risky long option

1. rm npm-shrinkwrap.json

   This is not ideal, as you may theoretically get lots of new versions of unrelated packages' dependencies, but it seems to be necessary; otherwise, because your new version of ember-cli has itself updated the versions of its dependencies to versions incompatible with those your shrinkwrap, you are going to end up with invalid packages. And that is something that npm shrinkwrap will not abide.

   Hey, at least this is happening to you on development, not a production deploy.

2. Update your package.json so your package is the version you want, rm -rf node_modules/ember-cli, and then npm install. Or, run

   npm install --save-dev --save-exact [email protected]

   Note that without --save-exact your package.json will use the ^ caret matcher. (Although this may not matter thanks to shrinkwrap anyway…?)

   (If one of these approaches works better for you, let me know and I will update this gist.)

   Pay attention to any npm WARN lines you may get. Some of these warnings (lack of README) are fine to ignore. Others (unmet dependency) will be considered hard errors by shrinkwrap, because consistency. (irony alert.) You may need to fix these upstream. This particular time, the cause was ember-cli having a bundledDependency that was incompatible with the versions specified by its other dependencies. Again, it's only a warning in npm install-land, but a serious, full-stop error to npm shrinkwrap. 💀 ☠ 💀

3. Finally, run

   npm shrinkwrap --dev

   This will recreate a new version of your shrinkwrap file.

   Note You may have to remove extraneous packages, because Shrinkwrap will yell at you and stop in its tracks if there are packages installed but not listed in package.json. For some reason (update: Because of harmony — this should not happen on ZDI), this means, for me, that I always seem to have to run rm -rf node_modules/npm-install-retry. ¯\_(ツ)_/¯

For what it's worth I just manually modified my npm shrinkwrap file, it's annoying but it works if you need to make small changes 🤷‍♂️