Repository navigation
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"
}
}
Activity
bsmithEG commentedon Aug 13, 2019
I had to come digging around in issues to find this, so something doc related would be greatly appreciated
mrchief commentedon Aug 2, 2020
Except that
--external nonedoesn't do anything. It doesn't even inline own source code, let alone dependencies. Using v0.12.3Produces just the main file with all requires intact:
adriandmitroca commentedon Sep 10, 2020
What about a bundle that should work directly via <script> tag?
IJMacD commentedon Sep 23, 2020
It seems like microbundle's focus is bundling libraries to be used in other JS apps.
I expected something like a micro version of webpack which generates self-contained js files ready to be used in
<script>tags on an html page.I too am unable to get thedevDependenciesor--external nonetricks to work. Output still includesrequire()calls.There may have been some caching issue or re-running
npm installbut the--externaloption now works for me.However the output still includes
module.exportswhich the browser balks at.adriandmitroca commentedon Sep 23, 2020
Hey @IJMacD
I've come up to a solution where I simply generate one extra bundle file for browsers purpose. See this:
https://github.com/adriandmitroca/mimeeq-auth-html-client/blob/master/package.json#L10
This generates extra index.standalone.umd.js file that can be used within the browser.
developit commentedon Dec 18, 2020
The doc now lives here:
https://github.com/developit/microbundle/wiki/How-Microbundle-decides-which-dependencies-to-bundle
delroh commentedon Oct 18, 2021
Maybe I am wrong here because the docs aren't clear but seems the reason is
require, regardless of the options used, is never inlined.src: #87 (comment)
And the docs say:
src: https://github.com/developit/microbundle/wiki/How-Microbundle-decides-which-dependencies-to-bundle
Which is confusing since
requirewon't be inlined either way? Spent hours wondering why it wasn't inlining despite using--external noneand moving dependencies betweendependenciesanddevDependencies, ultimately seems that if what you're trying to bundle usesrequire, you won't be able to make a standalone build file.Also, seems
readme.mdhasn't been updated with current CLI options. Some options and aliases are in thereadme.mdbut they're not currently shown inmicrobundle -h, which can also confuse.rschristian commentedon Oct 18, 2021
Which options are you referring to? I only see a singular difference, which is
--jsxImportSource, and maybe the documented--no-compress, which is a tad unnecessary to document. I'll certainly get that corrected, but let me know if I've missed something.delroh commentedon Oct 18, 2021
Didn't take note of all the ones I found, a sourcemap alias comes to mind and those you mention might be the rest. Sure it's just an alias but can be confusing at first.
delroh commentedon Oct 19, 2021
Another thing that confused me, in readme.md line 119:
Shouldn't that be
"umd:main"or"unpkg"since"main"is for CommonJS bundle?rschristian commentedon Oct 19, 2021
Not necessarily, no. What format you provide through
mainis up to you and the bundler/tools you plan on using the output with.delroh commentedon Oct 19, 2021
Not sure I understood, does that mean this would produce the same output of umd bundles?
What about this?
That's line 159 of readme.md I'm not understanding then.
And in line 164 of readme.md:
Filename suffix is not specified and the comment indicates it will produce a CommonJS bundle? is it because that's the default behavior?
rschristian commentedon Oct 19, 2021
Couple things:
What outputs are generated depends on the
--formatflag. By default, CJS, UMD, ESM, and Modern are output. Certain formats look to certain keys for guidance on what their file names should be, but at the moment, this is quite limited (hopefully changing in #896, but I digress).Assuming you're using default outputs, no,
./dist/foo.umd.jswould be generated as CJS in that scenario. We do not decide output based on filename. If you didn't generate CJS, I believe you wouldn't get matching output for"main".Yes, the CJS output gets mapped to
"main". In that case, it's a package with"type": "module"set, which necessitates the need for.cjs.rschristian commentedon Oct 19, 2021
It's worth mentioning that there's quite a big gap between what Microbundle outputs and what is valid and can be used by a package.
Microbundle's setup aims to provide users with a number of commonly used formats. However, if you choose to limit these formats, say by only outputting ESM as
"main", Microbundle isn't set up to handle this automatically. You'd need to run a post-build script to rename the output to match the"main"key. It will not know that you want to declare your output with a different key.So the
package.jsonfiles you see listed in the ReadMe might differ from what Microbundle is capable of outputting automatically, but they're not "wrong", if that makes sense.In the case of the UMD/
"main"example, I believe UMD output automatically gets the.umdsuffix in the case of not being able to find a key in the user'spackage.jsonfile. The filename is automatically provided, and that name just so happens to match what is written for"main".delroh commentedon Oct 19, 2021
Yes, I was thinking of it in terms of using
microbundlewithout options and specifying those fields inpackage.json. Makes sense that if a--formatis specified, it would takeover what format it would output onmain. It's more clear with what you explain, thank you.rschristian commentedon Oct 19, 2021
--formatis always "specified", as it has a default value (cjs,umd,esm,modern). And it doesn't really "takeover what format is output onmain. If you output CJS with Microbundle, Microbundle will try to match the CJS output filename to what you've specified withmain. However, if you've disabled CJS output, then Microbundle won't connectmainto anything. So whatever you specify inmain(if you specify it at all) is entirely up to you. Maybe you point it at your UMD output, or maybe your ESM. Microbundle won't ensure there's a file at that path though, so you as the user need to make sure it matches something if you do specify it.Microbundle's CJS output is tied to
main, but from the package side of things, there's no guarantee thatmainis CJS.If this sounds a bit complicated and like a bit of mess, in truth, it is. Build tools (including Node) can more or less look for arbitrary keys in your library's
package.jsonand expect arbitrary formats. What Microbundle tries to do is give you a great set of defaults that should work on all tools. However, you can also use Microbundle to output exactly what you desire, you just might need a post-build script or two to finish things off.