@rsbuild/plugin-umd
v1.0.4
Published
An Rsbuild plugin to generate outputs in [UMD](https://github.com/umdjs/umd) format.
Downloads
864
Readme
@rsbuild/plugin-umd
An Rsbuild plugin to generate outputs in UMD format.
UMD stands for Universal Module Definition, which is a module specification that is compatible with AMD, CommonJS, and global variable definition. UMD outputs refer to modules that follow the UMD specification, allowing them to be loaded and used in different environments, including browser and Node.js.
Usage
Install:
npm add @rsbuild/plugin-umd -DAdd plugin to your rsbuild.config.ts:
// rsbuild.config.ts
import { pluginUmd } from "@rsbuild/plugin-umd";
export default {
plugins: [pluginUmd()],
};Example
For example, the project contains the following code:
export function double(a) {
return a * 2;
}When using the UMD plugin, Rsbuild will generate a dist/index.js file in UMD format.
- When loading this file in a browser, you can access the exported content through a global variable on the window object, for example:
console.log(window.myLib.double(1)); // -> 2- When loading in Node.js, you can import it directly using
require, for example:
const { double } = require("./dist/index.js");
console.log(double(1)); // -> 2Options
name
name is a required field used to specify the name of the UMD library, corresponding to Rspack's output.library.name option.
- Type:
string - Example:
pluginUmd({
name: "foo", // accessed through window.foo
});export
Specifies which export to use as the content of the UMD library. By default, export is undefined, which exports the whole namespace object.
- Type:
string | string[] - Default:
undefined - Example: If
exportis configured asdefault, accessingwindow.foowill give you the content exported byexport default.
pluginUmd({
name: "foo",
export: "default",
});- Example 2: You can also pass an array to
output.library.export, and the array will be interpreted as an access path.
pluginUmd({
name: "foo",
export: ["default", "subModule"],
});export default {
// The value accessed through window.foo is 1
subModule: 1,
};Output Filename
By default, the UMD plugin will output a dist/index.js file. You can modify the name of the output file through Rsbuild's output.filename option.
For example, output a dist/myLib.js file:
export default {
output: {
filename: {
js: "myLib.js",
},
},
};If you need filename hash, enable the output.filenameHash option:
export default {
output: {
filenameHash: true,
},
};Debugging in the Browser
You can run the rsbuild dev command to debug UMD outputs in the browser.
First, create src/index.html and add the following code:
<!DOCTYPE html>
<html>
<head></head>
<body>
<script>
console.log(window.myLib.double(1));
</script>
</body>
</html>Then, specify the template in rsbuild.config.ts:
export default {
plugins: [pluginUmd({ name: "myLib" })],
html: {
template: "./src/index.html",
},
};Finally, run npx rsbuild dev to start.
HTML Generation
After using the UMD plugin, HTML files are not generated by default when running production builds. This is because UMD bundles are usually distributed as a library and do not rely on HTML files.
If you need to generate HTML files, you can set tools.htmlPlugin to true:
export default {
plugins: [pluginUmd({ name: "myLib" })],
html: {
template: "./src/index.html",
},
tools: {
htmlPlugin: true,
},
};Code Splitting
The UMD plugin overrides Rsbuild's default chunk splitting rules by setting performance.chunkSplit.strategy to all-in-one to output a single bundle. This is because UMD outputs are often distributed via CDN and allow direct referencing via <script> tags.
If you need to split the UMD outputs, you can actively configure performance.chunkSplit, for example:
export default {
performance: {
chunkSplit: {
strategy: "split-by-experience",
},
},
};Note that the UMD plugin does not disable splits caused by dynamic imports. If you need to disable this, you can set the Rspack's output.asyncChunks option to false:
export default {
tools: {
rspack: {
output: {
asyncChunks: false,
},
},
},
};License
MIT.