mirror of
https://github.com/developit/microbundle.git
synced 2026-01-25 14:06:50 +00:00
Readme Tweaks (#628)
This commit is contained in:
Jason Miller
GitHub
parent
a0525231a1
commit
083297733d
84
README.md
84
README.md
@ -9,7 +9,18 @@
|
||||
|
||||
---
|
||||
|
||||
## ✨ Features:
|
||||
<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])_
|
||||
@ -19,37 +30,40 @@
|
||||
- 0 configuration TypeScript support
|
||||
- Built-in Terser compression & gzipped bundle size tracking
|
||||
|
||||
## 🔧 Installation
|
||||
## 🔧 Installation & Setup <a name="setup"></a> <a name="installation"></a>
|
||||
|
||||
### Download
|
||||
1️⃣ **Install** by running: `npm i -D microbundle`
|
||||
|
||||
`npm i -D microbundle`
|
||||
|
||||
### Set up your `package.json`
|
||||
2️⃣ **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
|
||||
"name": "foo", // your package name
|
||||
"source": "src/foo.js", // your source code
|
||||
"main": "dist/foo.js", // where to generate the CommonJS/Node 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", // uses "source" and "main" as input and output paths by default
|
||||
"dev": "microbundle watch"
|
||||
"build": "microbundle", // compiles "source" to "main"/"module"/"unpkg"
|
||||
"dev": "microbundle watch" // re-build when source files change
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🤖 Modern Output
|
||||
3️⃣ **Try it out** by running `npm run build`.
|
||||
|
||||
Microbundle's `esm`, `cjs`, `umd` and `iife` output formats all compile your code to syntax that works pretty much everywhere. You can customize which browser or Node versions you wish to support by [adding a browserslist configuration](https://github.com/browserslist/browserslist#browserslist-), however the default setting is recommended for most cases since it supports as many browsers as possible.
|
||||
## 💽 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](https://github.com/browserslist/browserslist#browserslist-), 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 90% of web browsers without needing to be transpiled. Specifically, it uses [preset-modules](https://github.com/babel/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 `esm` bundle:
|
||||
|
||||
```js
|
||||
// Our source, "src/make-dom.js":
|
||||
export default async function makeDom(tag, props, children) {
|
||||
const el = document.createElement(tag);
|
||||
let el = document.createElement(tag);
|
||||
el.append(...(await children));
|
||||
return Object.assign(el, props);
|
||||
}
|
||||
@ -66,7 +80,7 @@ Compiling the above using Microbundle produces the following `modern` and `esm`
|
||||
|
||||
```js
|
||||
export default async function(e, t, a) {
|
||||
var n = document.createElement(e);
|
||||
let n = document.createElement(e);
|
||||
n.append(...await a);
|
||||
return Object.assign(n, t);
|
||||
}
|
||||
@ -86,7 +100,9 @@ export default function(e, t, r) { try {
|
||||
|
||||
</td></tbody></table>
|
||||
|
||||
This is enabled by default - all you have to do is add the field to your `package.json`. While the best way to point to modern source from a package.json is [still being discussed](https://twitter.com/_developit/status/1263174528974364675), you might choose to use the "module" field:
|
||||
This is enabled by default - all you have to do is add the field to your `package.json`.
|
||||
|
||||
<details><summary>💁♂️ <em>How to point to modern code in a package.json is <a href="https://twitter.com/_developit/status/1263174528974364675">being discussed</a>. You might use the "module" field.</em></summary>
|
||||
|
||||
```js
|
||||
{
|
||||
@ -98,15 +114,27 @@ This is enabled by default - all you have to do is add the field to your `packag
|
||||
}
|
||||
```
|
||||
|
||||
## 📦 Usage
|
||||
</details>
|
||||
|
||||
## 📦 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` / `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.
|
||||
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.
|
||||
```js
|
||||
{
|
||||
"source": "src/index.js", // input
|
||||
"main": "dist/my-library.js", // output
|
||||
"scripts": {
|
||||
"build": "microbundle"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For UMD builds, microbundle will use a snake_case version of the `name` field in your `package.json` as export name. This can be customized using an `"amdName"` key in your `package.json` or the `--name` command line argument.
|
||||
|
||||
### `microbundle watch`
|
||||
|
||||
@ -138,14 +166,16 @@ imports will be scoped.
|
||||
|
||||
### Specifying builds in `package.json`
|
||||
|
||||
You can specify output builds in a `package.json` as follows:
|
||||
Microbundle uses the fields from your `package.json` to figure out where it should place each generated bundle:
|
||||
|
||||
```
|
||||
"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
|
||||
{
|
||||
"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
|
||||
}
|
||||
```
|
||||
|
||||
### Mangling Properties
|
||||
@ -162,7 +192,7 @@ To achieve the smallest possible bundle size, libraries often wish to rename int
|
||||
|
||||
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
|
||||
### All CLI Options <a name="options"></a>
|
||||
|
||||
```
|
||||
Usage
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user