bundleDependencies is a package.json field that lists dependencies to pack inside your published tarball, so installers receive them as part of your package instead of resolving them from the registry. Scanners that read only manifests or lockfiles can miss that code, so check what your tools actually inspect.
How it works
The npm package.json documentation says you can bundle packages in a tarball by listing their names in the bundleDependencies array and then running npm pack to create the archive. The names carry no versions, because versions are specified in dependencies. A boolean form exists too: true bundles all dependencies and false bundles none.
The result is a package that carries its own copies of those dependencies. The consumer's install does not fetch them separately.
Why people use it
Typical reasons are shipping a command line tool that must work offline, freezing a known set of versions, or including a dependency that is not published to a registry. It is related to the shrinkwrap approach covered in npm-shrinkwrap.json vs package-lock.json, but different: shrinkwrap pins versions that are still fetched, while bundling ships the code.
The security trade-offs
- Frozen vulnerabilities. A bundled copy does not update when the upstream package is fixed. The consumer can only get the fix when you publish again.
- Scanner blind spots. A tool that reads a consumer's lockfile may see your package but not the packages inside its tarball, because they were never resolved from the registry as separate entries. Whether a tool inspects tarball contents varies, so test yours with a known vulnerable package.
- Provenance gaps. Registry metadata, such as publisher history for each bundled package, is not attached to the copies.
- Review difficulty. A diff of your repository shows names, while the real code lives in the packed archive.
What to do
- Search your own package.json and your direct dependencies for bundleDependencies.
- Unpack the tarball with npm pack and list what is inside, as in npm pack dry run.
- Run your scanner against the unpacked contents, or against a generated SBOM that includes bundled components.
- If you publish with bundled dependencies, re-publish promptly when an advisory affects one of them.
- Prefer normal dependencies when you do not need offline or frozen behavior.
| Approach | Where the code comes from | Updates with upstream fixes |
|---|---|---|
| Normal dependency | Registry at install time | Yes, within the version range |
| Shrinkwrap | Registry, pinned versions | Only when you republish |
| bundleDependencies | Your tarball | Only when you republish |
Try it yourself
Click through it at your own pace, or open it full screen.
Check what the inventory lists for a project and ask whether bundled code would appear in a view like this.
Quick check
Does bundleDependencies include versions?
No. The array holds package names only. Versions come from dependencies.
Will a bundled dependency get upstream fixes automatically?
No. The copy is inside the tarball, so you must publish a new release to update it.
Safeguard builds an SBOM and dependency inventory from your project, and the free scan at gold.safeguard.sh/scan is a quick way to see what is detected.
Sources
Last reviewed: 19 October 2026.
