Microbundle
📦 Zero-configuration bundler for tiny modules.
Install / Use
/learn @developit/MicrobundleREADME
<p align="center"> <strong>Guide → </strong> <a href="#setup">Setup</a> ✯ <a href="#formats">Formats</a> ✯ <a href="#modern">Modern Mode</a> ✯ <a href="#usage">Usage & Configuration</a> ✯ <a href="#options">All Options</a> </p>
✨ Features <a name="features"></a>
- One dependency to bundle your library using only a
package.json - Support for ESnext & async/await (via [Babel] & [async-to-promises])
- Produces tiny, optimized code for all inputs
- Supports multiple entry modules (
cli.js+index.js, etc) - Creates multiple output formats for each entry (<abbr title="CommonJS (node)">CJS</abbr>, <abbr title="Universal Module Definition">UMD</abbr> & <abbr title="ECMAScript Modules">ESM</abbr>)
- 0 configuration TypeScript support
- Built-in Terser compression & gzipped bundle size tracking
🔧 Installation & Setup <a name="setup"></a> <a name="installation"></a>
1️⃣ Install by running: npm i -D microbundle
2️⃣ Set up your package.json:
{
"name": "foo", // your package name
"type": "module",
"source": "src/foo.js", // your source code
"exports": {
"require": "./dist/foo.cjs", // used for require() in Node 12+
"default": "./dist/foo.modern.js" // where to generate the modern bundle (see below)
},
"main": "./dist/foo.cjs", // where to generate the CommonJS bundle
"module": "./dist/foo.module.js", // where to generate the ESM bundle
"unpkg": "./dist/foo.umd.js", // where to generate the UMD bundle (also aliased as "umd:main")
"scripts": {
"build": "microbundle", // compiles "source" to "main"/"module"/"unpkg"
"dev": "microbundle watch" // re-build when source files change
}
}
3️⃣ Try it out by running npm run build.
💽 Output Formats <a name="formats"></a>
Microbundle produces <code title="ECMAScript Modules (import / export)">esm</code>, <code title="CommonJS (Node-style module.exports)">cjs</code>, <code title="Universal Module Definition (works everywhere)">umd</code> bundles with your code compiled to syntax that works pretty much everywhere. While it's possible to customize the browser or Node versions you wish to support using a browserslist configuration, the default setting is optimal and strongly recommended.
🤖 Modern Mode <a name="modern"></a>
In addition to the above formats, Microbundle also outputs a modern bundle specially designed to work in all modern browsers.
This bundle preserves most modern JS features when compiling your code, but ensures the result runs in 95% of web browsers without needing to be transpiled.
Specifically, it uses Babel's "bugfixes" mode
(previously known as preset-modules) to target the set of browsers that support <script type="module"> - that allows syntax like async/await, tagged templates, arrow functions, destructured and rest parameters, etc.
The result is generally smaller and faster to execute than the plain esm bundle.
Take the following source code for example:
// Our source, "src/make-dom.js":
export default async function makeDom(tag, props, children) {
let el = document.createElement(tag);
el.append(...(await children));
return Object.assign(el, props);
}
Compiling the above using Microbundle produces the following modern and esm bundles:
export default async function (e, t, a) {
let n = document.createElement(e);
n.append(...(await a));
return Object.assign(n, t);
}
export default function (e, t, r) {
try {
var n = document.createElement(e);
return Promise.resolve(r).then(function (e) {
return n.append.apply(n, e), Object.assign(n, t);
});
} catch (e) {
return Promise.reject(e);
}
}
This is enabled by default. All you have to do is add an "exports" field to your package.json:
{
"main": "./dist/foo.umd.js", // legacy UMD output (for Node & CDN use)
"module": "./dist/foo.module.mjs", // legacy ES Modules output (for bundlers)
"exports": "./dist/foo.modern.mjs", // modern ES2017 output
"scripts": {
"build": "microbundle src/foo.js"
}
}
The "exports" field can also be an object for packages with multiple entry modules:
{
"name": "foo",
"exports": {
".": "./dist/foo.modern.mjs", // import "foo" (the default)
"./lite": "./dist/lite.modern.mjs", // import "foo/lite"
"./full": "./dist/full.modern.mjs" // import "foo/full"
},
"scripts": {
"build": "microbundle src/*.js" // build foo.js, lite.js and full.js
}
}
📦 Usage & Configuration <a name="usage"></a>
Microbundle includes two commands - build (the default) and watch.
Neither require any options, but you can tailor things to suit your needs a bit if you like.
microbundle– bundles your code once and exits. (alias:microbundle build)microbundle watch– bundles your code, then re-bundles when files change.
ℹ️ Microbundle automatically determines which dependencies to inline into bundles based on your
package.json.Read more about How Microbundle decides which dependencies to bundle, including some example configurations.
Specifying filenames in package.json
Unless overridden via the command line, microbundle uses the source property in your package.json to determine which of your JavaScript files to start bundling from (your "entry module").
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.
{
"source": "src/index.js", // input
"main": "dist/foo.js", // CommonJS output bundle
"umd:main": "dist/foo.umd.js", // UMD output bundle
"module": "dist/foo.mjs", // ES Modules output bundle
"exports": {
"types": "./dist/foo.d.ts", // TypeScript typings for NodeNext modules
"require": "./dist/foo.js", // CommonJS output bundle
"default": "./dist/foo.modern.mjs", // Modern ES Modules output bundle
},
"types": "dist/foo.d.ts" // TypeScript typings
}
When deciding which bundle to use, Node.js 12+ and webpack 5+ will prefer the exports property, while older Node.js releases use the main property, and other bundlers prefer the module field.
For more information about the meaning of the different properties, refer to the Node.js documentation.
For UMD builds, microbundle will use a camelCase version of the name field in your package.json as export name.
Alternatively, this can be explicitly set by adding an "amdName" key in your package.json, or passing the --name command line argument.
Usage with {"type":"module"} in package.json
Node.js 12.16+ adds a new "ES Module package", which can be enabled by adding {"type":"module"} to your package.json.
This property changes the default source type of .js files to be ES Modules instead of CommonJS.
When using {"type":"module"}, the file extension for CommonJS bundles generated by Microbundle must be changed to .cjs:
{
"type": "module",
"module": "dist/foo.js", // ES Module bundle
"main": "dist/foo.cjs", // CommonJS bundle
}
Additional Configuration Options
Config also can be overridded by the publishConfig property in your package.json.
{
"main": "src/index.ts", // this would be used in the dev environment (e.g. Jest)
"publishConfig": {
"source": "src/index.js", // input
"main": "dist/my-library.js", // output
},
"scripts": {
"build": "microbundle"
}
}
Building a single bundle with fixed output name
By default Microbundle outputs multiple bundles, one bundle per format. A single bundle with a fixed output name can be built like this:
microbundle -i lib/main.js -o dist/bundle.js --no-pkg-main -f umd
Using with TypeScript
Just point the input to a .ts file through either the cli or the source key in your package.json and you’re done.
Microbundle will generally respect your TypeScript config defined in a tsconfig.json file with notable exceptions being the "target" and "module" settings. To ensure your TypeScript configuration matches the configuration that Microbundle uses internally it's strongly recommended that you set "module": "ESNext" and "target": "ESNext" in your tsconfig.json.
To e
Related Skills
node-connect
347.0kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
frontend-design
107.8kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
openai-whisper-api
347.0kTranscribe audio via OpenAI Audio Transcriptions API (Whisper).
qqbot-media
347.0kQQBot 富媒体收发能力。使用 <qqmedia> 标签，系统根据文件扩展名自动识别类型（图片/语音/视频/文件）。
