Microbundle

The zero-configuration bundler for tiny modules, powered by Rollup.

Guide → Setup ✯ Formats ✯ Modern Mode ✯ Usage & Configuration ✯ All Options

✨ Features

• 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 (CJS, UMD & ESM)
• 0 configuration TypeScript support
• Built-in Terser compression & gzipped bundle size tracking

🔧 Installation & Setup

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": "./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

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.

🤖 Modern Mode

In addition to the above formats, Microbundle also outputs a

modern

esm

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

esm

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"

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"

{
    "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/full"
    },
    "scripts": {
        "build": "microbundle src/*.js" // build foo.js, lite.js and full.js
    }
}

📦 Usage & Configuration

Microbundle includes two commands -

build

watch

• 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

package.json

main

umd:main

module

exports

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.m.js",           // ES Modules output bundle 
  "exports": {
    "require": "./dist/foo.js",        // CommonJS output bundle
    "default": "./dist/foo.modern.js", // Modern ES Modules output bundle
  },
  "types": "dist/foo.d.ts"             // TypeScript typings directory
}

When deciding which bundle to use, Node.js 12+ and webpack 5+ will prefer the

exports

main

module

For UMD builds, microbundle will use a camelCase version of the

name

package.json

"amdName"

package.json

--name

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

.js

{"type":"module"}

.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

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

source

package.json

Microbundle will generally respect your TypeScript config defined in a

tsconfig.json

"module": "ESNext"

"target": "ESNext"

tsconfig.json

To ensure Microbundle does not process extraneous files, by default it only includes your entry point. If you want to include other files for compilation, such as ambient declarations, make sure to add either "files" or "include" into your

tsconfig.json

If you're using TypeScript with CSS Modules, you will want to set

"include": ["node_modules/microbundle/index.d.ts"]

tsconfig.json

CSS and CSS Modules

Importing CSS files is supported via

import "./foo.css"

--css inline

// 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.css

.css

--css-modules true

--no-css-modules

--css-modules false

The default scope name for CSS Modules is

_[name]__[local]__[hash:base64:5]

_[hash:base64:5]

--css-modules "[name]_[hash:base64:7]"

| 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: |

Building Module Workers

Microbundle is able to detect and bundle Module Workers when generating bundles in the

es

umd

modern

worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
// or simply:
worker = new Worker('./worker.js', { type: 'module' });

... then add the

--workers

microbundle --workers

For more information see @surma/rollup-plugin-off-main-thread.

Mangling Properties

To achieve the smallest possible bundle size, libraries often wish to rename internal object properties or class members to smaller names - transforming

this._internalIdValue

this._i

mangle.json

"mangle"

{
    "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.

Defining build-time constants

The

--define

@

| 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)

All CLI Options

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 --help
Options
    -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,esm,cjs,umd or iife) (default modern,esm,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
    --generateTypes    Whether or not to generate types, if types or typings is set in package.json then it will default to be true
    --css              Where to output CSS: "inline" or "external" (default: "external")
    --css-modules      Configures .css to be treated as modules (default: null)
    --workers          Bundle module workers - see https://git.io/J3oSF  (default false)
    -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

🛣 Roadmap

Here's what's coming up for Microbundle:

• [ ] Multiple separate inputs->outputs
• [x] TypeScript support
• [x] Flowtype support

🔨 Built with Microbundle

• Preact Fast 3kB React alternative with the same modern API. Components & Virtual DOM.
• Stockroom Offload your store management to a worker easily.
• Microenvi Bundle, serve, and hot reload with one command.
• Theme UI Build consistent, themeable React apps based on constraint-based design principles.
• react-recomponent Reason-style reducer components for React using ES6 classes.
• brazilian-utils Utils library for specific Brazilian businesses.
• react-hooks-lib A set of reusable react hooks.
• mdx-deck-live-code A library for mdx-deck to do live React and JS coding directly in slides.
• react-router-ext An Extended react-router-dom with simple usage.
• routex.js A dynamic routing library for Next.js.
• hooked-form A lightweight form-management library for React.
• goober Less than 1KB css-in-js alternative with a familiar API.
• react-model The next generation state management library for React

🥂 License

MIT