📦 Zero-configuration bundler for tiny modules.
The zero-configuration bundler for tiny modules, powered by Rollup.
Guide → Setup ✯ Formats ✯ Modern Mode ✯ Usage & Configuration ✯ All Options
package.json
cli.js+
index.js, etc)
1️⃣ Install by running:
npm i -D microbundle
2️⃣ Set up your
package.json:
{ "name": "foo", // your package name "source": "src/foo.js", // your source code "main": "dist/foo.js", // where to generate the CommonJS/Node bundle "exports": "./dist/foo.modern.js", // path to the modern output (see below) "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.
Microbundle produces esm
, cjs
, umd
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.
In addition to the above formats, Microbundle also outputs a
modernbundle 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 preset-modules to target the set of browsers that support - 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
esmbundle:
// 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
modernand
esmbundles:
make-dom.modern.js (117b)
|
make-dom.module.js (194b)
|
---|---|
|
|
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.js", // legacy ES Modules output (for bundlers) "exports": "./dist/foo.modern.js", // 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.js", // import "foo" (the default) "./lite": "./dist/lite.modern.js", // import "foo/lite" "./full": "./dist/full.modern.js" // import "foo" }, "scripts": { "build": "microbundle src/*.js" // build foo.js, lite.js and full.js } }
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 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.
microbundle/
microbundle build
Unless overridden via the command line, microbundle uses the
sourceproperty in your
package.jsonto locate the input file, and the
mainproperty for the output:
{ "source": "src/index.js", // input "main": "dist/my-library.js", // output "scripts": { "build": "microbundle" } }
For UMD builds, microbundle will use a camelCase version of the
namefield in your
package.jsonas export name. This can be customized using an
"amdName"key in your
package.jsonor the
--namecommand line argument.
microbundle watch
Acts just like
microbundle build, but watches your source files and rebuilds on any change.
Just point the input to a
.tsfile through either the cli or the
sourcekey in your
package.jsonand you’re done.
Microbundle will generally respect your TypeScript config defined in a
tsconfig.jsonfile 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.
Importing CSS files is supported via
import "./foo.css". By default, generated CSS output is written to disk. The
--css inlinecommand line option will inline generated CSS into your bundles as a string, returning the CSS string from the import:
// with the default external CSS: import './foo.css'; // generates a minified .css file in the output directory// with
microbundle --css inline
: import css from './foo.css'; console.log(css); // the generated minified stylesheet
CSS Modules: CSS files with names ending in
.module.cssare treated as a CSS Modules. To instead treat imported
.cssfiles as modules, run Microbundle with
--css-modules true. To disable CSS Modules for your project, pass
--no-css-modulesor
--css-modules false.
The default scope name for CSS Modules is
_[name]__[local]__[hash:base64:5]in watch mode, and
_[hash:base64:5]for production builds. This can be customized by passing the command line argument
--css-modules "[name]_[hash:base64:7]", using these fields and naming conventions.
| flag | import | is css module? | | ----- | ------------------------------ | :----------------: | | null | import './my-file.css'; | :x: | | null | import './my-file.module.css'; | :whitecheckmark: | | false | import './my-file.css'; | :x: | | false | import './my-file.module.css'; | :x: | | true | import './my-file.css'; | :whitecheckmark: | | true | import './my-file.module.css'; | :whitecheckmark: |
package.json
Microbundle uses the fields from your
package.jsonto figure out where it should place each generated bundle:
{ "main": "dist/foo.js", // CommonJS bundle "umd:main": "dist/foo.umd.js", // UMD bundle "module": "dist/foo.m.js", // ES Modules bundle "esmodule": "dist/foo.modern.js", // Modern bundle "types": "dist/foo.d.ts" // TypeScript typings directory }
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
To achieve the smallest possible bundle size, libraries often wish to rename internal object properties or class members to smaller names - transforming
this._internalIdValueto
this._i. Microbundle doesn't do this by default, however it can be enabled by creating a
mangle.jsonfile (or a
"mangle"property in your package.json). Within that file, you can specify a regular expression pattern to control which properties should be mangled. For example: to mangle all property names beginning an underscore:
{ "mangle": { "regex": "^_" } }
It's also possible to configure repeatable short names for each mangled property, so that every build of your library has the same output. See the wiki for a complete guide to property mangling in Microbundle.
The
--defineoption can be used to inject or replace build-time constants when bundling. In addition to injecting string or number constants, prefixing the define name with
@allows injecting JavaScript expressions.
| Build command | Source code | Output | |---------------|-------------|--------|
microbundle --define VERSION=2|
console.log(VERSION)|
console.log(2)
microbundle --define API_KEY='abc123'|
console.log(API_KEY)|
console.log("abc123")
microbundle --define @assign=Object.assign|
assign(a, b)|
Object.assign(a, b)
Usage $ microbundle [options]Available Commands build Build once and exit watch Rebuilds on any change
For more info, run any command with the
--help
flag $ microbundle build --help $ microbundle watch --helpOptions -v, --version Displays current version -i, --entry Entry module(s) -o, --output Directory to place build files into -f, --format Only build specified formats (any of modern,es,cjs,umd or iife) (default modern,es,cjs,umd) -w, --watch Rebuilds on any change (default false) --pkg-main Outputs files analog to package.json main entries (default true) --target Specify your target environment (node or web) (default web) --external Specify external dependencies, or 'none' (default peerDependencies and dependencies in package.json) --globals Specify globals dependencies, or 'none' --define Replace constants with hard-coded values (use @key=exp to replace an expression) --alias Map imports to different modules --compress Compress output using Terser --no-compress Disable output compressing --strict Enforce undefined global context and add "use strict" --name Specify name exposed in UMD and IIFE builds --cwd Use an alternative working directory (default .) --sourcemap Generate source map (default true) --raw Show raw byte size (default false) --jsx A custom JSX pragma like React.createElement (default: h) --jsxImportSource Specify the automatic import source for JSX like preact --tsconfig Specify the path to a custom tsconfig.json --css Where to output CSS: "inline" or "external" (default: "external") --css-modules Configures .css to be treated as modules (default: null) -h, --help Displays this message
Examples $ microbundle build --globals react=React,jquery=$ $ microbundle build --define API_KEY=1234 $ microbundle build --alias react=preact/compat $ microbundle watch --no-sourcemap # don't generate sourcemaps $ microbundle build --tsconfig tsconfig.build.json
Here's what's coming up for Microbundle: