Docs: Clarify Dependency Bundling #454
Description
Bundling of dependencies has a lot of value in certain situations. It's a technique that can allow libraries to import modules while mutating their behavior (through constant inlining or transforms), or to inline specific known working versions of modules that would otherwise be too difficult to offload to the module consumer.
However, it's possible Microbundle's behavior here is unclear. Here's what we currently do for web (--target node doesn't have these semantics and doesn't generally inline):
When you import a module in your library, Microbundle checks to see how that module was added to your package.json. If the module is listed in peerDependencies or dependencies, it will be considered "external" and won't be inlined into your bundled code - instead a require() or import will be left in place matching your source. If the module you imported is only referenced in your package.json's devDependencies, it will get inlined into the bundle.
This behaviour makes sense: when a package consumer installs your package, anything in dependencies gets downloaded with it, so it's assumed your package will use those co-installed versions. Similarly for peerDependencies, which aren't automatically downloaded by npm, but produce warnings when the target dependency is not installed or does not meet the package's version criteria.
So, how do you use Microbundle to bundle dependencies? Here's a quick reference:
1. I want to bundle a dependency
In your package.json, install that dependency as a devDependency - it's only going to be used at build time, since it'll be inlined when the user installs instead of dynamically downloaded and referenced.
{
"main": "dist/index.js",
"module": "dist/index.module.js",
"scripts": {
"build": "microbundle my-lib.js"
},
"devDependencies": {
"lib-to-bundle": "^1.2.3"
}
}2. I want to bundle specific dependencies
Sometimes projects have more than one build configuration, or run microbundle multiple times. It could be that you have a modern bundle and a legacy compatibility bundle, and the modern bundle inlines helpers. Or perhaps you are producing "development" and "production" builds, where each is different based on differing build-time constants. Regardless, in these situations it may be necessary to explicitly tell Microbundle which dependencies should be inlined, and which should be left as external.
{
"source": "my-lib.js",
"scripts": {
"build:standalone": "microbundle --external none --dist standalone.js",
"build:development": "microbundle --external pretty-format my-lib.development.js"
},
"dependencies": {
"pretty-format": "^1.2.3",
"debug": "^1.2.3"
}
}Notice how, in the above example's development build, only pretty-format is left external. Even though debug is listed in dependendencies, it will be inlined because it is not listed in the value passed to --external. When --external is specified, it overrides all defaults.
3. I want to explicitly bundle all dependencies
For cases similar to the above, sometimes you want to produce a bundle where all dependencies are inlined - even if they're specified as dependencies or peerDependencies in the package.json. One real-world example of this is preact-redux, since it needs to inline various dependencies in order to apply preact-specific transformations and optimizations to them at build time. For this, Microbundle has an option to force all dependencies to be inlined called --external none:
{
"source": "generic.js",
"scripts": {
"build:preact": "microbundle --external none --define PREACT=1 --dist preact.js",
"build:react": "microbundle --dist react.js"
},
"dependencies": {
"prop-types": "^1.2.3",
"some-other-lib": "^1.2.3"
}
}