[RFC] Surface Inline Bundled Dependencies in Package Pages

[sxzz]

Summary

Add first-class UI support for packages that physically inline their dependencies into their published tarball — making it possible for developers and consumers to understand what packages are silently shipped inside a bundle, and optionally estimate their implied download contribution.

npmx would recognize two sources of this information: the existing bundleDependencies / bundledDependencies field already supported by npm, and a new proposed inlinedDependencies field being discussed at e18e.

Note: The design of the inlinedDependencies field itself — naming, shape, and adoption strategy — is being discussed separately at e18e/ecosystem-issues#237. This RFC focuses on how npmx consumes and surfaces the data, assuming that standard lands.

Background: bundleDependencies Already Exists — But Is Not Enough

npm already supports a bundleDependencies field. When set, npm pack copies the listed packages from node_modules directly into the tarball. This is the mechanism behind packages like vite shipping cac — every npm install vite delivers a copy of cac, yet cac's download count reflects none of this. cac has 20M weekly downloads, and the real number is even higher.

However, bundleDependencies only covers the "copy from node_modules" case. It does not cover bundler-inlined code (Rollup, esbuild, etc.), which is equally common. The proposed inlinedDependencies field fills this gap as purely declarative metadata, covering any inlining method.

Proposed npmx Features

1. Display inlined dependencies on package pages

npmx would read both bundleDependencies / bundledDependencies and inlinedDependencies from the published package.json, surfacing them in a unified "Inlined Dependencies" section alongside the existing Dependencies / Dev Dependencies / Peer Dependencies panels.

Each entry should link to the inlined package's own npmx page, show the resolved version, and be visually distinguished to make the inlining relationship immediately clear.

2. Implied / Shadow Download Estimates

For each inlined dependency, npmx could display an "implied downloads" metric — an estimate of how many additional downloads the inlined package effectively received by being shipped inside the parent.

implied_downloads(inlined_pkg, parent_pkg) ≈ downloads(parent_pkg, period)

This could be surfaced in two places:

A. On the parent package page — show each inlined dep alongside the parent's download count as its implied contribution.

B. On the inlined package's own page — aggregate implied downloads from all packages that inline it:

Downloads (last week)
  Direct:    340,000
  Implied: 15,100,000  (via vite and 2 other packages)
  ──────────────────────
  Total:   15,440,000

3. Ecosystem-level "Most Inlined" discovery

A dedicated explore/stats page listing the most frequently inlined packages, ranked by number of packages that inline them or total implied download volume.

Implementation Notes

• npmx reads both bundleDependencies / bundledDependencies (existing) and inlinedDependencies (proposed, pending e18e discussion) from the published package.json.
• For implied downloads, npmx would query the npm download API (https://api.npmjs.org/downloads/point/{period}/{package}) per parent package, lazily and with caching to manage API load.
• Tarball inspection as a fallback for undeclared inlined deps is out of scope for this RFC.

Open Questions

1. Should "implied downloads" be opt-in in the UI to avoid confusing users unfamiliar with the concept?
2. Should npmx display bundleDependencies-sourced entries differently from inlinedDependencies-sourced entries?
3. Naming the metric — "Implied Downloads", "Shadow Downloads", "Bundled Reach"? Open to suggestions.

Alternatives Considered

• Do nothing: leaves a meaningful gap in ecosystem visibility.
• Show inlined deps without download estimates: a reasonable v1 scope.

Checklist

• Community feedback on UI design
• Agreement on "implied downloads" methodology
• API rate limit / caching strategy for download queries
• Design mockups
• inlinedDependencies standard finalized at e18e

This is an RFC — all details are open for discussion. For questions about the inlinedDependencies field standard itself, please join the conversation at e18e/ecosystem-issues#237.

[acutmore]

Packages listing the components that were used when they were built sounds like it might have decent overlap with SBOMs like https://github.com/CycloneDX/cyclonedx-node-npm, https://ecma-international.org/publications-and-standards/standards/ecma-424/

[johnnyreilly]

I think this is very interesting!

I very much favour proposed field shape option B. I'd very much want to know the version number of inlined dependencies.

For this to become successful (and this is true for anything) then adoption may be a challenge. It might be useful if tools like pnpm etc were also interested in this. I guess in this case I'm thinking about where packages inline other packages that may have security vulnerabilities etc

[naugtur]

This is a good spec.

I want to use the opportunity to push back against the broken concepts of bundled dependencies.

Security implications of bundled dependencies are a mess.

If we create a new way to document them, it'd be great if it was possible to define them in a way that's verifiable - that the contents actually match with what's bundled.

I understand it'd be hard to do for cases where a bundler processes a project and alters the sources. But that's what I'm after - the ability to declare the sources as altered or not, and if they're not altered, it should be possible to compare the contents of the unaltered folder with the original package.

And yes, I still don't understand why bundle dependencies without altering them but it's too late to undo. my main problem is npm runs their install scripts 🙈

Here's my research on what's bundled in top npm packages
https://github.com/naugtur/research/blob/main/bundled/bundleds.md

[sxzz]

For the inlinedDependencies field itself — the naming, shape, and adoption strategy — I've also opened a discussion over at e18e: e18e/ecosystem-issues#237

If you have thoughts on the standard (rather than the npmx UI), it might be a better venue to hash that out, since it's relevant beyond npmx. Happy to keep both threads in sync!

[sxzz]

@naugtur Great points, and that research is really valuable context.

To address the security concern directly: inlinedDependencies is designed as a good-faith declaration, not a security boundary. Security tooling should never trust it as a complete or accurate inventory — the entire package contents should still be scanned as-is. The field is metadata for observability and CVE correlation, not a skip list.

That said, your point about verifiability is interesting. For the unaltered case (i.e. bundleDependencies via npm pack), a content hash comparison against the original package is theoretically possible. For bundler-processed code, you're right that it's a much harder problem — the output is transformed enough that direct comparison breaks down. Perhaps inlinedDependencies could optionally declare whether the source was altered, e.g. as part of the field value, to at least make the distinction machine-readable.

On the CVE side — this is actually one of the stronger motivations for the field. Right now, if cac ships a vulnerability fix, nothing alerts vite users that they're running a vulnerable inlined copy. With inlinedDependencies declared, npm and security tools could surface that automatically.

On whether bundling dependencies is a good practice in the first place, the e18e blog has a good write-up: https://e18e.dev/blog/bundling-dependencies

[naugtur]

I like the cve implications. But don't understand why the inlined dependencies would not be listed as regular dependencies in the package. That used to be a convention. Are people putting them in dev dependencies now? Does it do anything more than conserve NPM's bandwidth?

Assuming this new convention is an improvement and gets adoption,
I see a potential gap here.

For vulnerability scanning we'd need to know the exact version of the package. Dependencies can be specified as ranges and even with a precise date of producing g a bundled artifact we wouldn't know what and when was installed before the build. So to know whether inlined version was vulnerable or not, a declaration of a specific version number is required for each inlined package.