npm-shrinkwrap stopping transitive dependencies being hoisted to top level node_modules of prototypes

[oscarduignan]

Description of the issue

I think the introduction of npm-shrinkwrap.json in last version is causing (not sure if always the case or there was a version conflict that caused it) the dependencies of the govuk-prototype-kit to only be installed in /node_modules/govuk-prototype-kit/node_modules/ where as they previously got hoisted up to /node_modules/

this can be an issue if someone had some code in their prototype that was trying to require() one of those dependencies - with no direct dependency

if they did an npm install before updating, then locally the prototype might run ok, but when pushed and a clean install is done, the dependencies aren't hoisted and it can fail with an error making it hard to debug

Steps to reproduce the issue

• created an example "vulnerable" prototype on v13.16.2 of prototype kit which imports express
  https://github.com/oscarduignan/2025-07-01-prototype/blob/main/app/routes.js#L6
• if you npm install and npm run dev that it will startup fine
• npm install govuk-prototype-kit@13.17.0
• if you run npm run dev again it will start
• remove the node_modules folder and npm install again (like if you pushed it to heroku or somewhere to deploy)
• if you run npm run dev now it will fail with error about missing express
  

to see the cause is npm-shrinkwrap.json

• cp node_modules/govuk-prototype-kit ../govuk-prototype-kit
• rm -rf ../govuk-prototype-kit/node_modules ../govuk-prototype-kit/npm-shrinkwrap.json
• rm -rf node_modules
• npm install ../govuk-prototype-kit
• npm run dev will start ok

you can see the difference in hoisting of dependencies by running "ls node_modules" on the different versions, and see how with shrinkwrap they aren't hoisted to top level node_modules

Actual vs expected behaviour

npm-shrinkwrap.json is probably useful, but it's quite a big change and the errors from this can be hard to debug

in the example, really the prototype we saw this on didn't need to import express, but it also wasn't hurting anything, and it is hard for maintainer to tell if it's ok to remove

might be worth a PSA in x-gov to make people aware of the risk of breakage when updating / considering if any mitigations that can be done (I'm not familiar enough with shrinkwrap to know if there are any ways to work around this)

Environment (where applicable)

N/A I think

• Node version: (not sure if it's impactful) v20.18.0
• Operating system: mac
• Browser:
• Browser version:
• GOV.UK Prototype Kit version: 13.17.0 (where npm-shrinkwrap.json was added to package.json file list)

[ch-ncolley]

I believe if the project moves from npm-shrinkwrap.json to package-lock.json (the current default for locking down dependencies) that this'll be resolved.

If this guidance is correct:

If you are publishing your package to npm, you have a choice between:

using a package-lock.json to record exactly which versions of dependencies you installed, but allowing people installing your package to use any version of the dependencies that is compatible with the version ranges dictated by your package.json, or
using an npm-shrinkwrap.json to guarantee that everyone who installs your package gets exactly the same version of all dependencies

https://stackoverflow.com/questions/44258235/what-is-the-difference-between-npm-shrinkwrap-json-and-package-lock-json

This file was introduced here:
#2413

[joelanman]

It's unclear to me that shrink wrap changes the hoisting behaviour - I can't find any clear documentation that that is the case (though it might be!)

The intention of the change was to lock down dependencies, as previously an updated dependency (sass) was causing issues.

If shrink wrap is the issue, possibly we can use specific version numbers in package.json instead.

However, if projects need dependencies they should install them directly, so I'm not sure if this is worth fixing, or it's better just tell people to install the dependencies they're missing instead of relying on hoisting.

[oscarduignan]

the idea of having some packages that have noisy updates (sass) use specific versions in package.json vs npm-shrinkwrap.json seems quite good to me

reading the npm docs, it says that npm-shrinkwrap.json is only recommended for applications being distributed as packages, not for libraries - because it locks out application maintainers from being able to update any transitive dependencies

[joelanman]

it locks out application maintainers from being able to update any transitive dependencies

that is our intention here - kit users are not generally devs and we'd prefer to manage packages ourselves. But I read this line as 'sticks to specific versions' and not 'prevents hoisting', but I could be wrong

[joelanman]

this came up again on support, they were using sync-request and express