The zero-configuration bundler for tiny modules, powered by Rollup.
--- ## β¨ 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 ### Download `npm i -D microbundle` ### Set up your `package.json` ```js { "source": "src/foo.js", // Your source file (same as 1st arg to microbundle) "main": "dist/foo.js", // output path for CommonJS/Node "module": "dist/foo.module.js", // output path for JS Modules "unpkg": "dist/foo.umd.js", // optional, for unpkg.com "scripts": { "build": "microbundle", // uses "source" and "main" as input and output paths by default "dev": "microbundle watch" } } ``` ### New: Modern JS Microbundle now has a new `modern` format (`microbundle -f modern`). Modern output still bundles and compresses your code, but it keeps useful syntax around that actually helps compression: ```js // Our source, "src/make-dom.js": export default async function makeDom(tag, props, children) { const el = document.createElement(tag); el.append(...(await children)); return Object.assign(el, props); } ``` Microbundle compiles the above to this: ```js export default async (e, t, a) => { const n = document.createElement(e); return n.append(...(await a)), Object.assign(n, t); }; ``` This is enabled by default - all you have to do is add the field to your `package.json`. You might choose to ship modern JS using the "module" field: ```js { "main": "dist/foo.umd.js", // legacy UMD bundle (for Node & CDN's) "module": "dist/foo.modern.module.js", // modern ES2017 bundle "scripts": { "build": "microbundle src/foo.js -f modern,umd" } } ``` ## π¦ Usage 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` / `microbundle build` Unless overridden via the command line, microbundle uses the `source` property in your `package.json` to locate the input file, and the `main` property for the output. For UMD builds, microbundle will use a snake case version of the `name` field in your `package.json` as export name. This can be overridden either by providing an `amdName` key in your `package.json` or via the `--name` flag in the cli. ### `microbundle watch` Acts just like `microbundle build`, but watches your source files and rebuilds on any change. ### 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. ### Using CSS Modules By default any css file imported as `.module.css`, will be treated as a css-module. If you wish to treat all .css imports as a module, specify the cli flag `--css-modules true`. If you wish to disable all css-module behaviours set the flag to `false`. The default scope name when css-modules is turned on will be, in watch mode `_[name]__[local]__[hash:base64:5]` and when you build `_[hash:base64:5]`. This can be overriden by specifying the flag, eg `--css-modules "_something_[hash:base64:7]"`. _Note:_ by setting this, it will be treated as a true, and thus, all .css imports will be scoped. | flag | import | is css module? | | ----- | ------------------------------ | :----------------: | | null | import './my-file.css'; | :x: | | null | import './my-file.module.css'; | :white_check_mark: | | false | import './my-file.css'; | :x: | | false | import './my-file.module.css'; | :x: | | true | import './my-file.css'; | :white_check_mark: | | true | import './my-file.module.css'; | :white_check_mark: | ### Specifying builds in `package.json` You can specify output builds in a `package.json` as follows: ``` "main": "dist/foo.js", // CJS bundle "umd:main": "dist/foo.umd.js", // UMD bundle "module": "dist/foo.m.js", // ES Modules bundle "source": "src/foo.js", // custom entry module (same as 1st arg to microbundle) "types": "dist/foo.d.ts", // TypeScript typings ``` ### 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` to `this._i`. Microbundle doesn't do this by default, however it can be enabled by creating a `mangle.json` file (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: ```json { "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](https://github.com/developit/microbundle/wiki/mangle.json).** ### All CLI Options ``` Usage $ microbundle