Microbundle

0.15.1 · active · verified Sun Apr 19

Microbundle is a zero-configuration bundler for small JavaScript libraries, currently at version 0.15.1. Powered by Rollup, it simplifies the build process by automatically generating optimized bundles in multiple formats: CommonJS (CJS), ECMAScript Modules (ESM), Universal Module Definition (UMD), and a 'modern' ESM bundle for contemporary browsers. It supports ESnext features, async/await, multiple entry points, TypeScript out-of-the-box, built-in Terser compression, and gzipped bundle size tracking. While not adhering to a strict release cadence, it receives frequent updates, often in the form of patch releases, indicating active maintenance. Key differentiators include its minimal setup (often just `package.json` configuration) and focus on producing tiny, performant outputs with modern browser targets by default.

Common errors

```
Error: 'source' field missing from package.json
```
cause Microbundle requires a `source` field in `package.json` to identify the primary entry point(s) for your library.

fix Add a `"source": "src/index.js"` (or your actual source file path) entry to your `package.json`.
```
SyntaxError: Cannot use import statement outside a module
```
cause This typically occurs when a CommonJS consumer tries to `require()` an ESM bundle or vice-versa, or when Node.js encounters an `import` statement in a file treated as CommonJS.

fix Ensure your `package.json`'s `main`, `module`, and `exports` fields correctly point to the appropriate CJS and ESM bundles. For Node.js, ensure `type: "module"` is set for ESM-only packages, or use `.mjs`/`.cjs` extensions explicitly in `exports`.
```
TypeError: Cannot read properties of undefined (reading 'length') related to CSS bundling.
```
cause This error (or similar unexpected behavior with CSS) can occur in Microbundle versions prior to v0.15.1 when multiple entry files reference distinct CSS assets, as the bundler might fail to process all of them correctly.

fix Update Microbundle to version `0.15.1` or newer. If the issue persists, verify your CSS import paths and ensure they are valid for bundling.

Warnings

breaking Starting with v0.15.0, Microbundle now outputs ESM files with the `.mjs` extension when the `package.json` type is explicitly set to `"type": "module"` and the target is CJS, or if the package type is CJS and ESM is output.
Fix: Update your import paths and `package.json` 'exports' fields to correctly reference `.mjs` files where applicable, especially when migrating projects or upgrading from older Microbundle versions. Ensure your build pipeline and consuming applications correctly resolve `.mjs` extensions.
gotcha When bundling multiple entry points that reference different CSS assets, versions prior to 0.15.1 might incorrectly bundle only the CSS referenced by the first entry point, leading to missing styles in other bundles.
Fix: Upgrade to Microbundle v0.15.1 or later to ensure all CSS assets across multiple entry points are correctly packaged.
gotcha Terser annotations (e.g., `/*@__NOINLINE__*/`) might have been incorrectly removed during the Babel pass in versions prior to v0.13.3, impacting optimization hints.
Fix: Upgrade to Microbundle v0.13.3 or later to ensure Terser annotations are correctly preserved during the build process.
gotcha Relying solely on `main` and `module` fields in `package.json` without the `exports` field can lead to incorrect module resolution, especially in modern Node.js environments or when supporting different environments (ESM vs CJS).
Fix: Always define the `exports` field in your `package.json` alongside `main` and `module` to ensure robust and explicit module resolution for various environments, as shown in the quickstart example.

Install

npm install microbundle npm
yarn add microbundle yarn
pnpm add microbundle pnpm

Imports

microbundle
wrong:
```
import microbundle from 'microbundle';
// or
const microbundle = require('microbundle');
```
correct:
```
/* Microbundle is a CLI tool. Use via package.json scripts or npx. */
```
Microbundle is primarily a Command Line Interface (CLI) tool. It is not designed for programmatic import as a library. Its functionality is accessed via the `microbundle` command line utility, typically executed through `package.json` scripts like `npm run build` or directly with `npx microbundle`. Direct `import` or `require` of the package itself will not expose a callable API but rather execute the CLI logic.
build command
wrong:
```
import { build } from 'microbundle';
```
correct:
```
npm run build
// or
npx microbundle
```
There is no `build` function exported by Microbundle for programmatic use. All bundling operations are configured and initiated via the command line interface, using options specified in `package.json` or as CLI flags. The recommended way to run it is through npm/yarn scripts or `npx`.
watch command
wrong:
```
import { watch } from 'microbundle';
```
correct:
```
npm run dev
// (where 'dev' script is 'microbundle watch')
// or
npx microbundle watch
```
Similar to the `build` command, there is no `watch` function exported. The `microbundle watch` command is part of the CLI for continuous rebuilding during development. Attempting to import a `watch` function will result in an undefined export or module resolution error.

Quickstart

Demonstrates a typical `package.json` setup for Microbundle, defining input/output paths for CJS, ESM, UMD, and modern bundles, along with example source code. Shows how to integrate Microbundle into `npm` scripts for building and watching files.

{
  "name": "my-tiny-lib",
  "version": "1.0.0",
  "type": "module",
  "source": "src/index.js",
  "exports": {
    "require": "./dist/index.cjs",
    "default": "./dist/index.modern.js"
  },
  "main": "./dist/index.cjs",
  "module": "./dist/index.module.js",
  "unpkg": "./dist/index.umd.js",
  "scripts": {
    "build": "microbundle",
    "dev": "microbundle watch"
  },
  "devDependencies": {
    "microbundle": "^0.15.0"
  }
}

// src/index.js
export const greet = (name) => `Hello, ${name}!`;
export default function sum(a, b) {
  return a + b;
}

// To run: 
// 1. npm install
// 2. npm run build
// This will generate dist/index.cjs, dist/index.modern.js, dist/index.module.js, dist/index.umd.js

view raw JSON →