Docs: Clarify Dependency Bundling

[developit]

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"
  }
}

[bsmithEG]

I had to come digging around in issues to find this, so something doc related would be greatly appreciated

[mrchief]

Except that --external none doesn't do anything. It doesn't even inline own source code, let alone dependencies. Using v0.12.3

microbundle -f cjs --target node --external none

Produces just the main file with all requires intact:

[adriandmitroca]

What about a bundle that should work directly via <script> tag?

[IJMacD]

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 the devDependencies or --external none tricks to work. Output still includes require() calls.

There may have been some caching issue or re-running npm install but the --external option now works for me.

However the output still includes module.exports which the browser balks at.

[adriandmitroca]

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]

The doc now lives here:
https://github.com/developit/microbundle/wiki/How-Microbundle-decides-which-dependencies-to-bundle

[delroh]

Except that --external none doesn't do anything. It doesn't even inline own source code, let alone dependencies. Using v0.12.3

microbundle -f cjs --target node --external none

Produces just the main file with all requires intact:

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.

If you use require(), you're opting out of bundling of that package entirely. Microbundle only bundles ES Modules imports in source.

src: #87 (comment)

And the docs say:

Microbundle decides whether a dependency should be inlined or left as an import / require() based on how you declare dependencies in your package.json.

If the module is listed in the "peerDependencies" or "dependencies" fields, it will be considered external and won't be inlined into your bundled code. External modules remain runtime dependencies of your bundle using require() or import.

src: https://github.com/developit/microbundle/wiki/How-Microbundle-decides-which-dependencies-to-bundle

Which is confusing since require won't be inlined either way? Spent hours wondering why it wasn't inlining despite using --external none and moving dependencies between dependencies and devDependencies, ultimately seems that if what you're trying to bundle uses require, you won't be able to make a standalone build file.

Also, seems readme.md hasn't been updated with current CLI options. Some options and aliases are in the readme.md but they're not currently shown in microbundle -h, which can also confuse.

[rschristian]

Also, seems readme.md hasn't been updated with current CLI options. Some options and aliases are in the readme.md but they're not currently shown in microbundle -h, which can also confuse.

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]

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]

Another thing that confused me, in readme.md line 119:

...
"main": "./dist/foo.umd.js", // legacy UMD output (for Node & CDN use)
...

Shouldn't that be "umd:main" or "unpkg" since "main" is for CommonJS bundle?

[rschristian]

Not necessarily, no. What format you provide through main is up to you and the bundler/tools you plan on using the output with.

[delroh]

Not sure I understood, does that mean this would produce the same output of umd bundles?

...
"main": "./dist/foo.umd.js",,
"umd:main": "./dist/foo.unpkg.js",
...

What about this?

The filenames and paths for generated bundles in each format are defined by the main, umd:main, module and exports properties in your package.json.

That's line 159 of readme.md I'm not understanding then.

And in line 164 of readme.md:

...
 "main": "dist/foo.js",               // CommonJS output bundle
...

Filename suffix is not specified and the comment indicates it will produce a CommonJS bundle? is it because that's the default behavior?

[rschristian]

Couple things:

What outputs are generated depends on the --format flag. 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.js would 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".

Filename suffix is not specified and the comment indicates it will produce a CommonJS bundle? is it because that's the default behavior?

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]

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.json files 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 .umd suffix in the case of not being able to find a key in the user's package.json file. The filename is automatically provided, and that name just so happens to match what is written for "main".

[delroh]

Yes, I was thinking of it in terms of using microbundle without options and specifying those fields in package.json. Makes sense that if a --format is specified, it would takeover what format it would output on main. It's more clear with what you explain, thank you.

[rschristian]

--format is always "specified", as it has a default value (cjs,umd,esm,modern). And it doesn't really "takeover what format is output on main. If you output CJS with Microbundle, Microbundle will try to match the CJS output filename to what you've specified with main. However, if you've disabled CJS output, then Microbundle won't connect main to anything. So whatever you specify in main (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 that main is 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.json and 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.