Skip to content

Can we axe npm-shrinkwrap.json #8938

Closed
Closed

Description

@G-Rath

I'd like to discuss the deprecation and eventual removal of support for npm-shrinkwrap.json from the cli, or some alternatives.

As I understand it (and have experienced so far):

  • npm-shrinkwrap.json can be included as part of any published package
  • it causes the whole tree under the package its included in to be locked
  • it takes priority over overrides
  • it is not supported by any other package manager

This creates an environment where downstream developers lose a lot of control over their dependency tree, which is particularly painful for dealing with security alerts as it makes you reliant on the upstream package to publish a new version with an updated shrinkwrap, even if they are not directly using the package in question!

The alternatives to deal with this include ignoring alerts, which is dangerous since you could become complacent and eventually let a very real vulnerability slip through, or switch to another package manager since this is an NPM-only problem (which can be particularly tempting to those in environments that have zero-vulns policies, which are very real even if some people think it's silly).

This also means deduplication can be hard, which can be sizable in the JS ecosystem due to the number of small packages that are often used.

I also don't think shrinkwraps are commonly used - the only real world example I know is netlify-cli, and people (including myself) have been trying to get that changed; this has previously surprised maintainers, and the creator of npm has said that shrinkwraps were a mistake.


I propose either:

  1. deprecating and removing npm-shrinkwarp.json entirely
  2. adding a flag of some kind to allow downstream developers to opt-out
    • this way you'd be able to just add an .npmrc to your project and not have to worry
  3. allow overrides to take priority over shrink wrapping
    • technically this is against the point of shrinkwrap, but I think it's still a valid option to suggest

Activity

  1. taylorreece commented on Jan 27, 2026

    @taylorreece

    We should take inspiration from CSS, and add an !important directive that overrides shrinkwrap:

    {
      "overrides": {
        "bar": {
          "foo": "1.0.0 !important"
        }
      }
    }
    

    I'm absolutely joking, of course!

    In all seriousness, I keep getting bitten by shrinkwrap, enough that I'm starting to avoid packages that use them. I'd love to see it go away.

  2. wraithgar commented on Feb 6, 2026

    @wraithgar
    Contributor

    The idea of bundled dependencies (of which shrinkwrap is one facet) is important to npm itself. We could not publish npm without it. npm has to ship as a complete unit. All of the dependencies it needs to install packages already have to come with it, because otherwise it would not be able to install its own dependencies. npm install -g npm requires this.

    npm does not use the npm-shrinkwrap.json file but it does use bundleDependencies which does basically the same thing under the hood.

    The real issue to solve here, and one which I think is worth exploring, is allowing for overrides to take place even in a bundled/shrinkwrap setting. The discussion would be one of priority, I think.

  3. wraithgar commented on Feb 6, 2026

    @wraithgar
    Contributor

    I also don't think shrinkwraps are commonly used

    tap used to bundle dependencies but it looks like that was removed after tap@16

  4. ljharb commented on Feb 7, 2026

    @ljharb
    Contributor

    fwiw, i added a shrinkwrap rule to https://npmjs.com/eslint-plugin-lockfile / https://npmjs.com/lintlock, if you want to prevent deps from introducing shrinkwraps to your graph.

  5. G-Rath commented on Feb 8, 2026

    @G-Rath
    ContributorAuthor

    npm does not use the npm-shrinkwrap.json file but it does use bundleDependencies which does basically the same thing under the hood.

    That feels a bit weird - is there a reason for that?

    The real issue to solve here, and one which I think is worth exploring, is allowing for overrides to take place even in a bundled/shrinkwrap setting.

    Yeah as I said I'm happy with any option just so long as I can take control over my dependency tree 🤷

    Personally I like the .npmrc config option as it feels like it'd be the easiest to do right now, but I agree that having overrides take priority over everything would be the most flexible

    The discussion would be one of priority, I think.

    I think that overrides should take priority over everything as much as possible, as its only respected in the root package.json so it should only be (ab)usable by developer at the end of the dependency chain, whose the one managing the env


    I've not used bundleDependencies myself and the docs don't seem to go into too much detail, but having a quick play locally with npm as a dependency it seems that as soon as you introduce a dependency on a bundled dependency, the entire dependency tree for npm gets moved into node_modules/npm/node_modules.

    That doesn't surprise me, but makes me think (combined with the dicussions so far):

    1. npm-shrinkwrap.json feels like it could still go because it can be almost replicated with bundleDependencies (only downside is you have to list all the top level dependencies explicitly, but you could introduce support for e.g. * if that was considered important), and it seems to be supported by the other package managers making it more standard (though Yarn v1 apparently called it bundledDependencies?)
    2. it might make it harder to support having overrides take priority, as the observed behaviour to me implies potentially more custom logic so it might be more work than just e.g. "moving applyOverrides to be after applyShrinkwrap"
  6. wraithgar commented on Feb 9, 2026

    @wraithgar
    Contributor

    bundleDependencies and bundledDependencies are both things npm checks for because of the ease at which they can be conflated/accidentally confused.

    If there is a way to drop shrinkwrap support altogether without affecting bundled dependencies that would work. I think the argument there is that a shrinkwrap file is much easier to have in there by coincidence, whereas declaring bundled dependencies is more on purpose? Do I understand what you're seeing there correctly?

    There is also something to be said for preventing them in your tree rather than ignoring them. This is an approach that is non-breaking. It also potentially puts pressure on places that are using them when they don't need to, which would fix it for all users, not just ones whose package managers ignore the file.

    I don't think we have any strong opinions on this outside of "npm itself absolutely still has to be able to ship itself fully bundled".

  7. wraithgar commented on Feb 9, 2026

    @wraithgar
    Contributor

    Some input from @wesleytodd in the openjs slack:

    ... I think the goal should be:

    1. Have a standard way that npm itself uses for it’s CLI to deliver an optimized CLI package for use primarily via npx
    2. Have a standard way for package authors to ship opinions on the shape of their dependencies that consumers can take control of via overrides
    3. Allow for package authors to specify dependencies included in the package source but not via npm managed tooling
  8. wraithgar commented on Feb 9, 2026

    @wraithgar
    Contributor

    I have added a link to this issue in our "cli future breaking changes" issue

  9. G-Rath commented on Feb 9, 2026

    @G-Rath
    ContributorAuthor

    I think the argument there is that a shrinkwrap file is much easier to have in there by coincidence, whereas declaring bundled dependencies is more on purpose? Do I understand what you're seeing there correctly?

    Yeah I think mostly - the only package I know of with a shrinkwrap is using it intentionally, so I'm not sure if "coincidence" is the right word, but I think very similar if not the same argument would be that shrinkwarp is an npm-specific version which is independent of package.json, making it surprising.

    Declaring bundled dependencies is more explicit and its in "the place where dependencies are specified" for our ecosystem so much less surprising.

    The two main advantages I can think of for shrinkwrap vs bundled dependencies are:

    • you don't have to specify every package (which could be supported via a special * value)
    • it captures the entire dependency tree in terms of versions etc, similar to an SBOM (which should be the same as a lockfile, which if you really wanted you could include in the published package)

    There is also something to be said for preventing them in your tree rather than ignoring them

    I'm not sure if I follow this - are you saying a flag that'd have npm reject packages with a shrinkwrap? In theory I'm in favor of this, but I don't see how in practice it'd put pressure upstream rather than downstream. The only package with a shrinkwrap I know of is netlify-cli who believe they do need it and is not replaceable with another package, so unless this flag was on by default, I don't see how it'd be useful.

    Some input from @wesleytodd in the openjs slack:

    ... I think the goal should be:

    I think those goals are on the money, and that right now we have 1. and 3. but not 2. due to overrides not having the highest priority

  10. owlstronaut commented on Apr 21, 2026

    @owlstronaut
  11. RandomByte commented on Apr 22, 2026

    @RandomByte

    We use npm-shrinkwrap in all our CLI tools (as was recommended). We believe this is a good way to 1) protect our users from supply chain attacks since we control dependency updates and 2) be able to easily reproduce issues our users are facing, which can often be caused by (transitive) dependency updates

    I guess it's fair to push the responsibility for maintaining lockfiles to the consumers of a package (or more likely, Dependabot), and I understand this to be the main point of the discussion here. But how is a developer realistically protected from installing a malicious package when installing packages globally on their system (as recommended for our UI5 CLI) or using npx (like for our MCP Server)?

    Would bundleDependencies be your recommendation in such cases? Wouldn't that lead to very large packages while still having the same problems that npm-shrinkwrap has?

    Regarding:

    downstream developers lose a lot of control over their dependency tree, which is particularly painful for dealing with security alerts

    We've experienced this as well. In our projects, we have to regularly publish updates to the npm-shrinkwrap because of security audit alerts, even though the vast majority of them actually pose no real risk for our users (e.g. because the affected API is not used). I would love for npm audit to allow package maintainers to flag a "vulnerable" dependency as a false positive.

    On the other hand, by using npm-shrinkwrap we have successfully protected our users from actual supply chain attacks in the past. This was a strong argument when we internally discussed abandoning npm-shrinkwrap in our projects due to the high maintenance efforts.

  12. owlstronaut commented on Apr 22, 2026

    @owlstronaut

    We use npm-shrinkwrap in all our CLI tools (as was recommended). We believe this is a good way to 1) protect our users from supply chain attacks since we control dependency updates and 2) be able to easily reproduce issues our users are facing, which can often be caused by (transitive) dependency updates

    I guess it's fair to push the responsibility for maintaining lockfiles to the consumers of a package (or more likely, Dependabot), and I understand this to be the main point of the discussion here. But how is a developer realistically protected from installing a malicious package when installing packages globally on their system (as recommended for our UI5 CLI) or using npx (like for our MCP Server)?

    Would bundleDependencies be your recommendation in such cases? Wouldn't that lead to very large packages while still having the same problems that npm-shrinkwrap has?

    Regarding:

    downstream developers lose a lot of control over their dependency tree, which is particularly painful for dealing with security alerts

    We've experienced this as well. In our projects, we have to regularly publish updates to the npm-shrinkwrap because of security audit alerts, even though the vast majority of them actually pose no real risk for our users (e.g. because the affected API is not used). I would love for npm audit to allow package maintainers to flag a "vulnerable" dependency as a false positive.

    On the other hand, by using npm-shrinkwrap we have successfully protected our users from actual supply chain attacks in the past. This was a strong argument when we internally discussed abandoning npm-shrinkwrap in our projects due to the high maintenance efforts.

    Yes, bundleDependencies is the recommended path for shipping a CLI with a locked tree, including global installs and npx. It's a stronger guarantee than shrinkwrap, as there is nothing left to resolve on the user's machine. Tarballs are larger on download, but the installed footprint is the same - and we think this is a reasonable tradeoff.

    I hear you on audit ergonomics. Feel free to draft a proposal in npm/rfcs

  13. ljharb commented on Apr 22, 2026

    @ljharb
    Contributor

    People shouldn't be installing things globally anyways, precisely because there's no global package.json or lockfile.

  14. 36degrees commented on Sep 11, 2026

    @36degrees
    Contributor

    The real issue to solve here, and one which I think is worth exploring, is allowing for overrides to take place even in a bundled/shrinkwrap setting. The discussion would be one of priority, I think.

    […]

    ... I think the goal should be:

    1. Have a standard way that npm itself uses for it’s CLI to deliver an optimized CLI package for use primarily via npx
    2. Have a standard way for package authors to ship opinions on the shape of their dependencies that consumers can take control of via overrides
    3. Allow for package authors to specify dependencies included in the package source but not via npm managed tooling

    […]

    I think those goals are on the money, and that right now we have 1. and 3. but not 2. due to overrides not having the highest priority

    Is allowing overrides to override bundled dependencies currently captured anywhere outside of this issue? It would also really help us in our context. Is there anything we can do to help move things forward?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions