Advantages of bundledDependencies over normal dependencies in NPM

npm allows us to specify bundledDependencies but what are the advantages of doing so? I guess if we want to make absolutely sure we get the right version even if the module we reference gets deleted, or perhaps there is a speed benefit with bundling?

Anyone know the advantages of bundledDependencies over normal dependencies?

Extract of bundledDependencies definition here for convenience:

bundledDependencies
Array of package names that will be bundled when publishing the package.

If this is spelled "bundleDependencies", then that is also honorable.

E.g. bundledDependencies: ['foo', 'bar']

One of the biggest problems right now with Node is how fast it is changing. This means that production systems can be very fragile and an npm update can easily break things.

Using bundledDependencies is a way to get round this issue by ensuring, as you correctly surmise, that you will always deliver the correct dependencies no matter what else may be changing.

You can also use this to bundle up your own, private bundles and deliver them with the install.

For the quick reader : this QA is about the package.json bundledDependencies field, not about the package.

What bundledDependencies do

"bundledDependencies" are exactly what their name implies. Dependencies that should be inside your project. So the functionality is basically the same as normal dependencies. They will also be packed when running npm pack.

When to use them

In practice they differ from however. Normal dependencies are usually installed from npm. Not bundled dependencies.

Thus bundled dependencies are useful where normal dependencies are not :

  • when you want to re-use a third party library that doesn't come from npm or that you modified
  • when you want to re-use your own projects as modules
  • you want to distribute some files with your module

This way, you don't have to create (and maintain) your own npm repository, but get the same benefits that you get from npm packages.

When not to use bundled dependencies

When developing, I don't think that the main point is to prevent accidental updates though. We have better tools for that, namely code repositories (git, mercurial, svn...) or npm shrinkwrap. The best practices regarding those tools are discussed on the node.js blog on the joyent developer websites.

In short : use npm shrinkwrap most of the time, and sometimes put the whole thing, including the node_module folder, into your code repository.

See also

This is a bit outside the scope of the question, but I'd like to mention the last kind of dependencies (that I know of) : peer dependencies. Also see this related SO question

Other advantage is that you can put your internal dependencies (application components) there and then just requiring them in your app as if they are independent modules instead of cluttering your lib/ and publishing them to npm.

If/when they are matured to the point they could live as separate modules, you can put them on npm easily, without modifying your code.