Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rspack-contrib/rsbuild-plugin-umd
An Rsbuild plugin to generate outputs in UMD format.
https://github.com/rspack-contrib/rsbuild-plugin-umd
rsbuild rsbuild-plugin rspack
Last synced: 16 days ago
JSON representation
An Rsbuild plugin to generate outputs in UMD format.
- Host: GitHub
- URL: https://github.com/rspack-contrib/rsbuild-plugin-umd
- Owner: rspack-contrib
- License: mit
- Created: 2024-07-05T13:35:59.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-12-01T10:09:41.000Z (25 days ago)
- Last Synced: 2024-12-01T11:19:48.245Z (25 days ago)
- Topics: rsbuild, rsbuild-plugin, rspack
- Language: TypeScript
- Homepage:
- Size: 67.4 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-rspack - @rsbuild/plugin-umd
README
# @rsbuild/plugin-umd
An Rsbuild plugin to generate outputs in [UMD](https://github.com/umdjs/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:
```bash
npm add @rsbuild/plugin-umd -D
```
Add plugin to your `rsbuild.config.ts`:
```ts
// rsbuild.config.ts
import { pluginUmd } from "@rsbuild/plugin-umd";
export default {
plugins: [pluginUmd()],
};
```
## Example
For example, the project contains the following code:
```js title="src/index.js"
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:
```js
console.log(window.myLib.double(1)); // -> 2
```
- When loading in Node.js, you can import it directly using `require`, for example:
```js
const { double } = require("./dist/index.js");
console.log(double(1)); // -> 2
```
## Options
### name
`name` is a required field used to specify the name of the UMD library, corresponding to Rspack's [output.library.name](https://rspack.dev/config/output#outputlibraryname) option.
- **Type:** `string`
- **Example:**
```js
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 `export` is configured as `default`, accessing `window.foo` will give you the content exported by `export default`.
```js
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.
```js
pluginUmd({
name: "foo",
export: ["default", "subModule"],
});
```
```js title="src/index.js"
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](https://rsbuild.dev/config/output/filename) option.
For example, output a `dist/myLib.js` file:
```js
export default {
output: {
filename: {
js: "myLib.js",
},
},
};
```
If you need filename hash, enable the [output.filenameHash](https://rsbuild.dev/config/output/filename-hash) option:
```js
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:
```html title="src/index.html"
console.log(window.myLib.double(1));
```
Then, specify the `template` in `rsbuild.config.ts`:
```ts title="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](https://rsbuild.dev/config/tools/html-plugin) to `true`:
```ts title="rsbuild.config.ts"
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 `` tags.
If you need to split the UMD outputs, you can actively configure [performance.chunkSplit](https://rsbuild.dev/config/performance/chunk-split), for example:
```js
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](https://rspack.dev/config/output#outputasyncchunks) option to `false`:
```js
export default {
tools: {
rspack: {
output: {
asyncChunks: false,
},
},
},
};
```
## License
[MIT](./LICENSE).