microbundle

<p align="center"> <img src="https://i.imgur.com/LMEgZMh.gif" width="597" alt="microbundle"> </p> <h1 align="center"> Microbundle <a href="https://www.npmjs.org/package/microbundle"><img src="https://yellow-cdn.veclightyear.com/835a84d5/628646fa-be22-4c53-84fb-fb6e861150e5.svg?style=flat" alt="npm"></a> <a href="https://travis-ci.org/developit/microbundle"><img src="https://yellow-cdn.veclightyear.com/835a84d5/bb4a7b50-6bbf-4749-8ca3-9973fd6bea04.svg?branch=master" alt="travis"></a> <a href="https://licenses.dev/npm/microbundle"><img src="https://licenses.dev/b/npm/microbundle" alt="licenses" /></a> </h1> <p align="center">一个由<a href="https://github.com/rollup/rollup">Rollup</a>驱动的<strong>零配置</strong>打包工具，专为<em>小型模块</em>设计。</p>

<p align="center"> <strong>指南 → </strong> <a href="#setup">设置</a> ✯ <a href="#formats">格式</a> ✯ <a href="#modern">现代模式</a> ✯ <a href="#usage">用法和配置</a> ✯ <a href="#options">所有选项</a> </p>

✨ 特性 <a name="features"></a>

仅需一个依赖，只通过package.json就能打包你的库
支持ESnext和async/await（通过Babel和async-to-promises）
为所有输入生成小巧、优化的代码
支持多个入口模块（cli.js + index.js等）
为每个入口创建多种输出格式（<abbr title="CommonJS (node)">CJS</abbr>、<abbr title="Universal Module Definition">UMD</abbr>和<abbr title="ECMAScript Modules">ESM</abbr>）
零配置TypeScript支持
内置Terser压缩和gzip打包大小跟踪

🔧 安装与设置 <a name="setup"></a> <a name="installation"></a>

1️⃣ 安装：运行 npm i -D microbundle

2️⃣ 设置 package.json：

{
  "name": "foo",                      // 你的包名
  "type": "module",
  "source": "src/foo.js",             // 你的源代码
  "exports": {
    "require": "./dist/foo.cjs",      // 用于Node 12+中的require()
    "default": "./dist/foo.modern.js" // 生成现代包的位置（见下文）
  },
  "main": "./dist/foo.cjs",           // 生成CommonJS包的位置
  "module": "./dist/foo.module.js",   // 生成ESM包的位置
  "unpkg": "./dist/foo.umd.js",       // 生成UMD包的位置（也别名为"umd:main"）
  "scripts": {
    "build": "microbundle",           // 将"source"编译到"main"/"module"/"unpkg"
    "dev": "microbundle watch"        // 当源文件变化时重新构建
  }
}

3️⃣ 试一试：运行 npm run build。

💽 输出格式 <a name="formats"></a>

Microbundle生成<code title="ECMAScript模块（import / export）">esm</code>、<code title="CommonJS（Node风格的module.exports）">cjs</code>、<code title="通用模块定义（适用于所有环境）">umd</code>包，将你的代码编译成几乎在任何地方都能运行的语法。虽然可以使用browserslist配置来自定义你想要支持的浏览器或Node版本，但默认设置是最优的，强烈推荐使用。

🤖 现代模式 <a name="modern"></a>

除了上述格式外，Microbundle还输出一个专门为_所有现代浏览器_设计的modern包。这个包在编译你的代码时保留了大多数现代JS特性，同时确保结果可以在95%的网页浏览器中运行，无需进行转译。具体来说，它使用了Babel的"bugfixes"模式（之前称为preset-modules）来针对支持<script type="module">的浏览器集合 - 这允许使用async/await、标签模板、箭头函数、解构和剩余参数等语法。结果通常比普通的esm包更小，执行速度更快。

例如，以下源代码：

// 我们的源代码，"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);
}

使用Microbundle编译上述代码会生成以下modern和esm包：

<table> <thead><tr> <th align="left"><code>make-dom.modern.js</code> <sup>(117字节)</sup></th> <th align="left"><code>make-dom.module.js</code> <sup>(194字节)</sup></th> </tr></thead> <tbody><tr valign="top"><td>

export default async function (e, t, a) {
	let n = document.createElement(e);
	n.append(...(await a));
	return Object.assign(n, t);
}

</td><td>

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

</td></tbody></table>

这是默认启用的。 你只需在package.json中添加一个"exports"字段：

{
	"main": "./dist/foo.umd.js", // 传统UMD输出（用于Node和CDN）
	"module": "./dist/foo.module.mjs", // 传统ES模块输出（用于打包工具）
	"exports": "./dist/foo.modern.mjs", // 现代ES2017输出
	"scripts": {
		"build": "microbundle src/foo.js"
	}
}

对于具有多个入口模块的包，"exports"字段也可以是一个对象：

{
	"name": "foo",
	"exports": {
		".": "./dist/foo.modern.mjs", // import "foo"（默认）
		"./lite": "./dist/lite.modern.mjs", // import "foo/lite"
		"./full": "./dist/full.modern.mjs" // import "foo/full"
	},
	"scripts": {
		"build": "microbundle src/*.js" // 构建foo.js、lite.js和full.js
	}
}

📦 用法和配置 <a name="usage"></a>

Microbundle包含两个命令 - build（默认）和watch。这两个命令都不需要任何选项，但你可以根据需要进行一些调整。

microbundle – 一次性打包你的代码并退出。（别名：microbundle build）
microbundle watch – 打包你的代码，然后在文件变化时重新打包。

ℹ️ Microbundle根据你的package.json自动确定哪些依赖项应该内联到包中。

阅读更多关于Microbundle如何决定哪些依赖项要打包的信息，包括一些示例配置。

在package.json中指定文件名

除非通过命令行覆盖，microbundle使用package.json中的source属性来确定从哪个JavaScript文件开始打包（你的"入口模块"）。每种格式生成的包的文件名和路径由package.json中的main、umd:main、module和exports属性定义。

{
  "source": "src/index.js",             // 输入
  "main": "dist/foo.js",                // CommonJS输出包
  "umd:main": "dist/foo.umd.js",        // UMD输出包
  "module": "dist/foo.mjs",             // ES模块输出包
  "exports": {
    "types": "./dist/foo.d.ts",         // NodeNext模块的TypeScript类型
    "require": "./dist/foo.js",         // CommonJS输出包
    "default": "./dist/foo.modern.mjs", // 现代ES模块输出包
  },
  "types": "dist/foo.d.ts"              // TypeScript类型
}

在决定使用哪个包时,Node.js 12+和webpack 5+会优先选择exports属性,而较旧的Node.js版本使用main属性,其他打包工具则偏好module字段。有关不同属性含义的更多信息,请参阅Node.js文档。

对于UMD构建,microbundle会使用package.json中name字段的驼峰式版本作为导出名称。或者,可以通过在package.json中添加"amdName"键,或传递--name命令行参数来显式设置。

在`package.json`中使用`{"type":"module"}`

Node.js 12.16+添加了一个新的"ES模块包",可以通过在package.json中添加{"type":"module"}来启用。此属性改变了.js文件的默认源类型,从CommonJS改为ES模块。当使用{"type":"module"}时,Microbundle生成的CommonJS包的文件扩展名必须改为.cjs:

{
  "type": "module",
  "module": "dist/foo.js",  // ES模块包
  "main": "dist/foo.cjs",   // CommonJS包
}

额外的配置选项

配置也可以通过package.json中的publishConfig属性覆盖。

{
  "main": "src/index.ts",          // 这将在开发环境中使用(如Jest)
  "publishConfig": {
    "source": "src/index.js",      // 输入
    "main": "dist/my-library.js",  // 输出
  },
  "scripts": {
    "build": "microbundle"
  }
}

构建单个固定输出名称的包

默认情况下,Microbundle输出多个包,每种格式一个包。可以这样构建单个固定输出名称的包:

microbundle -i lib/main.js -o dist/bundle.js --no-pkg-main -f umd

与TypeScript一起使用

只需通过命令行或package.json中的source键将输入指向.ts文件即可。

Microbundle通常会遵循tsconfig.json文件中定义的TypeScript配置,但值得注意的例外是"target"和"module"设置。为确保TypeScript配置与Microbundle内部使用的配置匹配,强烈建议在tsconfig.json中设置"module": "ESNext"和"target": "ESNext"。

为确保Microbundle不处理多余的文件,默认情况下它只包含您的入口点。如果您想包含其他文件进行编译,比如环境声明,请确保在tsconfig.json中添加"files"或"include"。

如果您在使用TypeScript时使用CSS Modules,您需要在tsconfig.json中设置"include": ["node_modules/microbundle/index.d.ts"],以告诉TypeScript如何处理CSS Module导入。

为确保您模块的.d.ts类型信息对使用moduleResolution: 'NodeNext'的其他TypeScript项目可见,请在package.json的相应exports映射中添加types键。

CSS和CSS模块

支持通过import "./foo.css"导入CSS文件。默认情况下,生成的CSS输出会写入磁盘。--css inline命令行选项会将生成的CSS内联到您的包中作为字符串,并从导入中返回CSS字符串:

// 默认外部CSS:
import './foo.css'; // 在输出目录中生成一个压缩的.css文件

// 使用`microbundle --css inline`:
import css from './foo.css';
console.log(css); // 生成的压缩样式表

CSS模块: 名称以.module.css结尾的CSS文件被视为CSS模块。要将导入的.css文件视为模块,请使用--css-modules true运行Microbundle。要禁用项目的CSS模块,请传递--no-css-modules或--css-modules false。

CSS模块的默认作用域名称在监视模式下为_[name]__[local]__[hash:base64:5],在生产构建中为_[hash:base64:5]。可以通过传递命令行参数--css-modules "[name]_[hash:base64:7]"来自定义,使用这些字段和命名约定。

标志	导入	是否为CSS模块?
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:

构建模块工作器

在生成esm和modern格式的包时,Microbundle能够检测和打包模块工作器。要使用此功能,请按如下方式实例化Web Worker:

worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
// 或简单地:
worker = new Worker('./worker.js', { type: 'module' });

...然后在构建命令中添加--workers标志:

microbundle --workers

更多信息请参见@surma/rollup-plugin-off-main-thread。

可视化包组成

使用--visualize标志在构建时生成一个stats.html文件,显示包的组成。使用rollup-plugin-visualizer。

混淆属性

为了实现最小的包大小,库经常希望将内部对象属性或类成员重命名为更短的名称 - 将this._internalIdValue转换为this._i。Microbundle默认不这样做,但可以通过创建mangle.json文件(或在package.json中添加"mangle"属性)来启用。在该文件中,您可以指定一个正则表达式模式来控制应该混淆哪些属性。例如:要混淆所有以下划线开头的属性名称:

{
	"mangle": {
		"regex": "^_"
	}
}

还可以为每个混淆的属性配置可重复的短名称,以便您的库的每次构建都有相同的输出。有关Microbundle中属性混淆的完整指南,请参阅wiki。

定义构建时常量

--define选项可用于在打包时注入或替换构建时常量。除了注入字符串或数字常量外,在定义名称前加上@可以注入JavaScript表达式。

构建命令	源代码	输出
`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)`

所有CLI选项 <a name="options"></a>

用法
	$ microbundle <命令> [选项]

可用命令
	build    构建一次并退出
	watch    在任何更改时重新构建

要获取更多信息,请在任何命令后加上`--help`标志运行
	$ microbundle build --help
	$ microbundle watch --help

选项 -v, --version 显示当前版本 -i, --entry 入口模块 -o, --output 放置构建文件的目录 -f, --format 仅构建指定格式（可为modern、esm、cjs、umd或iife中的任意一种）（默认为modern,esm,cjs,umd） -w, --watch 在任何更改时重新构建（默认为false） --pkg-main 输出与package.json主入口类似的文件（默认为true） --target 指定目标环境（node或web）（默认为web） --external 指定外部依赖，或'none'（默认为package.json中的peerDependencies和dependencies） --globals 指定全局依赖，或'none' --define 用硬编码值替换常量（使用@key=exp替换表达式） --alias 将导入映射到不同的模块 --compress 使用Terser压缩输出（当--target为web时默认为true，当--target为node时默认为false） --strict 强制使用未定义的全局上下文并添加"use strict" --name 指定在UMD和IIFE构建中暴露的名称 --cwd 使用替代工作目录（默认为.） --sourcemap 生成源映射（默认为true） --raw 显示原始字节大小（默认为false） --jsx 自定义JSX pragma，如React.createElement（默认为h） --jsxFragment 自定义JSX fragment pragma，如React.Fragment（默认为Fragment） --jsxImportSource 声明用于导入jsx工厂函数的模块说明符 --tsconfig 指定自定义tsconfig.json的路径 --generateTypes 是否生成类型，如果在package.json中设置了types或typings，则默认为true --css CSS输出位置："inline"或"external"（默认为"external"） --css-modules 将.css文件视为模块（默认为null） --workers 打包模块workers - 参见 https://github.com/surma/rollup-plugin-off-main-thread#auto-bundling （默认为false） --visualize 生成包组成可视化（stats.html） -h, --help 显示此消息

示例 $ microbundle build --globals react=React,jquery=$ $ microbundle build --define API_KEY=1234 $ microbundle build --alias react=preact/compat $ microbundle watch --no-sourcemap # 不生成源映射 $ microbundle build --tsconfig tsconfig.build.json