UMD 插件

用于构建 UMD 格式的产物。

什么是 UMD

UMD 是 Universal Module Definition 的缩写,它是同时兼容 AMD、CommonJS 和全局变量定义方式的模块规范。UMD 产物指的是遵循 UMD 规范的模块,它能够在多种环境中被加载和使用,包括浏览器环境和 Node.js 环境。

快速开始

安装插件

你可以通过如下的命令安装插件:

npm
yarn
pnpm
bun
npm add @rsbuild/plugin-umd -D

注册插件

你可以在 rsbuild.config.ts 文件中注册插件:

rsbuild.config.ts
import { pluginUmd } from '@rsbuild/plugin-umd';

export default {
  plugins: [pluginUmd({ name: 'myLib' })],
};

示例

比如项目中有以下代码:

src/index.js
export function double(a) {
  return a * 2;
}

在使用 UMD 插件时,Rsbuild 构建会生成 UMD 格式的 dist/index.js 文件。

  • 在浏览器中加载该文件时,可以通过 window 上的全局变量访问其中导出的内容,比如:
console.log(window.myLib.double(1)); // -> 2
  • 在 Node.js 中加载时,可以直接通过 require 导入,比如:
const { double } = require('./dist/index.js');

console.log(double(1)); // -> 2

选项

name

name 为必填字段,用于指定 UMD library 的名称,对应 Rspack 的 output.library.name 选项。

  • 类型: string
  • 示例:
pluginUmd({
  name: 'foo', // 通过 window.foo 访问
});

export

指定将哪一个导出作为 UMD library 的内容。在默认情况下,export 是 undefined,这将导出整个命名空间对象。

  • 类型: string | string[]
  • 默认值: undefined
  • 示例:export 配置为 default,那么通过 window.foo 访问的是 export default 导出的内容。
pluginUmd({
  name: 'foo',
  export: 'default',
});
  • 示例二: 你也可以将数组传递给 output.library.export,数组会被解析为一个访问路径。
pluginUmd({
  name: 'foo',
  export: ['default', 'subModule'],
});
src/index.js
export default {
  // 通过 window.foo 访问的值为 1
  subModule: 1,
};

产物名称

默认情况下,UMD 插件会构建出 dist/index.js 文件,你可以通过 Rsbuild 的 output.filename 来修改产物文件的名称。

比如输出 dist/myLib.js 文件:

export default {
  output: {
    filename: {
      js: 'myLib.js',
    },
  },
};

在浏览器中调试

你可以运行 rsbuild dev 命令来在浏览器中调试 UMD 产物。

首先,创建 src/index.html,并添加调用代码:

src/index.html
<!doctype html>
<html>
  <head></head>
  <body>
    <script>
      console.log(window.myLib.double(1));
    </script>
  </body>
</html>

然后在 rsbuild.config.ts 中指定 template

rsbuild.config.ts
export default {
  plugins: [pluginUmd({ name: 'myLib' })],
  html: {
    template: './src/index.html',
  },
};

最后运行 npx rsbuild dev 即可。