105

npm allows us to specify bundleDependencies, 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?

4
  • 17
    'If this is spelled "bundleDependencies", then that is also honorable.' Great documentation! Jun 26, 2012 at 12:46
  • 11
    And yet, somehow, fixing it to merely read "is also honored" feels sad. In a tight spot, if I ordered up a samurai or knight for aid, I'd definitely like him to come bundled with compatible weapons and armor--and to be honorable.
    – Jon Coombs
    May 12, 2015 at 21:45
  • 3
    "I guess if we want to make absolutely sure we get the right version even if the module we reference gets deleted" suddenly carries a lot of weight: blog.npmjs.org/post/141577284765/kik-left-pad-and-npm
    – joews
    Mar 24, 2016 at 11:06
  • 1
    Also see stackoverflow.com/questions/11459475/… .
    – Anon
    Jul 14, 2017 at 13:31

6 Answers 6

119

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

Normal dependencies are usually installed from the npm registry. Thus bundled dependencies are useful when:

  • you want to re-use a third party library that doesn't come from the npm registry or that was modified
  • 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 now lock files.

To pin your package versions, you can use:

  • Option1: Use the newer NPM version 5 that comes with node 8. It uses a package-lock.json file (see the node blog and the node 8 release)

  • Option2: use yarn instead of npm. It is a package manager from facebook, faster than npm and it uses a yarn.lock file. It uses the same package.json otherwise.

This is comparable to lockfiles in other package managers like Bundler or Cargo. It’s similar to npm’s npm-shrinkwrap.json, however it’s not lossy and it creates reproducible results.

npm actually copied that feature from yarn, amongst other things.

  • Option3: this was the previously recommended approach, which I do not recommend anymore. The idea was to use npm shrinkwrap most of the time, and sometimes put the whole thing, including the node_module folder, into your code repository. Or possibly use shrinkpack. The best practices at the time were discussed on the node.js blog and on the joyent developer websites.

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 and possibly the docs of yarn on bundledDependencies.

7
  • 6
    "including the node_module folder" - it's a pretty strange thing which pollutes your repo with generated code... especially when you are working with native modules...
    – Oleksandr
    Jul 22, 2015 at 11:38
  • @Olexandr Between that and risking that a package breaks you app, I guess the choice is easy. Note that you could put in a separate branch (if using git for instance). Agreed, it is far from an ideal solution.
    – nha
    Jul 22, 2015 at 12:23
  • 4
    I would recommend against checking in node_modules because of packages like phantomjs for example, which install the appropriate binary for the current system. This means that if one Dev runs npm install on Linux and checks in node_modules – it won't work for another Dev who clones the repo on Windows. It's better to check in the tarballs which npm install downloads and point npm-shrinkwrap.json at them. You can automate this process using the npm install -g shrinkpack tool. Jul 15, 2016 at 8:14
  • 1
    Thanks @nha, your be protected from that with shrinkpack also, as the registry tarballs would be in your project repository. Dec 29, 2016 at 12:37
  • 1
    @fold_left yes indeed, thanks for pointing it (and for making shrinkpack). I was just saying that all this could have been avoided if the npm registry was acting like an immutable datastore.
    – nha
    Dec 29, 2016 at 16:05
50

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.

3
  • 1
    How does it always delivers the correct dependencies? Does this means npm update won't affect any dependencies in bundledDependencies? Dec 21, 2015 at 4:56
  • 2
    Yes, correct. Note that the bundled dependencies might not be "correct" in any fundamental way. They are just what the person doing bundling SAID was correct. Dec 21, 2015 at 18:28
  • 7
    Maybe because you are looking at an answer that is five and a half years old! The amount that Node.JS has moved on in that time is phenomenal. Perhaps you would like to add something useful as a comment instead? Mar 4, 2018 at 20:30
25

Other advantage is that you can put your internal dependencies (application components) there and then just require them in your app as if they were 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.

5

I'm surprised I didn't see this here already, but when carefully selected, bundledDependencies can be used to produce a distributable package from npm pack that will run on a system where npm is not configured. This is helpful if you have e.g. a system that's not networked / not on the internet: bring your package over on a thumb drive (or whatever) and unpack the tarball, then npm run or node index.js and it Just Works.

Maybe there's a better way to bundle up your application to run "offline", but if there is I haven't found it.

1

Suppose you're using pnpm to manage a monorepo and you have a utils folder. To access this folder, you could do one of the following (the last option uses bundledDependencies):

  • Use relative imports, which may end up looking ugly, confusing, breaking encapsulation, and it may even break if you ever change the location of the folder without updating the imports.
  • As a nicer option, if you're using TypeScript, you could alias the path of the utils folder to whatever name you want like, well, "utils". As a result every child package would only need to refer to the alias, and if you ever change the location of the utils folder you only need to change the path in the tsconfig.json. BUT, this will break if you define another tsconfig.json in a child package that also uses "paths" (the alias option)
  • You could use bundledDependencies to maintain a private and local utils package that users will never be able to download from npm but you'll still be able to use them in your public packages. This way you also get to reference it by its name instead of the relative path

Of course, the solution may not always be to use bundledDependencies, every problem has its own specific requirements, but I find bundledDependencies to be very useful for that particular use case that happens often with monorepos.

0

Operationally, I look at bundledDependencies as a module's private module store, where dependencies is more public, resolved among your module and its dependencies (and sub-dependencies). Your module may rely on an older version of, say, react, but a dependency requires latest-and-greatest. Your package/install will result in your pinned version in node_modules/$yourmodule/node_modules/react, while your dependency will get their version in node_modules/react (or node_modules/$dependency/node_modules/react if they're so inclined).

A caveat: I recently ran into a dependency that did not properly configure its dependency on react, and having react in bundledDependencies caused that dependent module to fail at runtime.

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.