{"id":13678109,"url":"https://github.com/rspack-contrib/rsbuild-plugin-umd","last_synced_at":"2025-04-14T10:13:52.898Z","repository":{"id":246899348,"uuid":"824600723","full_name":"rspack-contrib/rsbuild-plugin-umd","owner":"rspack-contrib","description":"An Rsbuild plugin to generate outputs in UMD format.","archived":false,"fork":false,"pushed_at":"2025-04-01T03:21:18.000Z","size":101,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-14T10:13:47.016Z","etag":null,"topics":["rsbuild","rsbuild-plugin","rspack"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rspack-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-05T13:35:59.000Z","updated_at":"2025-04-01T03:21:19.000Z","dependencies_parsed_at":"2024-08-07T08:55:37.775Z","dependency_job_id":"e82ebd1c-75c5-4e08-bc2a-285f3f186ceb","html_url":"https://github.com/rspack-contrib/rsbuild-plugin-umd","commit_stats":null,"previous_names":["rspack-contrib/rsbuild-plugin-umd"],"tags_count":5,"template":false,"template_full_name":"rspack-contrib/rsbuild-plugin-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-umd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-umd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-umd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-umd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rspack-contrib","download_url":"https://codeload.github.com/rspack-contrib/rsbuild-plugin-umd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248860167,"owners_count":21173342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rsbuild","rsbuild-plugin","rspack"],"created_at":"2024-08-02T13:00:50.219Z","updated_at":"2025-04-14T10:13:52.877Z","avatar_url":"https://github.com/rspack-contrib.png","language":"TypeScript","funding_links":[],"categories":["Plugins"],"sub_categories":["Rsbuild Plugins"],"readme":"# @rsbuild/plugin-umd\n\nAn Rsbuild plugin to generate outputs in [UMD](https://github.com/umdjs/umd) format.\n\n\u003e 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.\n\n\u003cp\u003e\n  \u003ca href=\"https://npmjs.com/package/@rsbuild/plugin-umd\"\u003e\n   \u003cimg src=\"https://img.shields.io/npm/v/@rsbuild/plugin-umd?style=flat-square\u0026colorA=564341\u0026colorB=EDED91\" alt=\"npm version\" /\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square\u0026colorA=564341\u0026colorB=EDED91\" alt=\"license\" /\u003e\n\u003c/p\u003e\n\n## Usage\n\nInstall:\n\n```bash\nnpm add @rsbuild/plugin-umd -D\n```\n\nAdd plugin to your `rsbuild.config.ts`:\n\n```ts\n// rsbuild.config.ts\nimport { pluginUmd } from \"@rsbuild/plugin-umd\";\n\nexport default {\n  plugins: [pluginUmd()],\n};\n```\n\n## Example\n\nFor example, the project contains the following code:\n\n```js title=\"src/index.js\"\nexport function double(a) {\n  return a * 2;\n}\n```\n\nWhen using the UMD plugin, Rsbuild will generate a `dist/index.js` file in UMD format.\n\n- When loading this file in a browser, you can access the exported content through a global variable on the window object, for example:\n\n```js\nconsole.log(window.myLib.double(1)); // -\u003e 2\n```\n\n- When loading in Node.js, you can import it directly using `require`, for example:\n\n```js\nconst { double } = require(\"./dist/index.js\");\n\nconsole.log(double(1)); // -\u003e 2\n```\n\n## Options\n\n### name\n\n`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.\n\n- **Type:** `string`\n- **Example:**\n\n```js\npluginUmd({\n  name: \"foo\", // accessed through window.foo\n});\n```\n\n### export\n\nSpecifies which export to use as the content of the UMD library. By default, `export` is undefined, which exports the whole namespace object.\n\n- **Type:** `string | string[]`\n- **Default:** `undefined`\n- **Example:** If `export` is configured as `default`, accessing `window.foo` will give you the content exported by `export default`.\n\n```js\npluginUmd({\n  name: \"foo\",\n  export: \"default\",\n});\n```\n\n- **Example 2:** You can also pass an array to `output.library.export`, and the array will be interpreted as an access path.\n\n```js\npluginUmd({\n  name: \"foo\",\n  export: [\"default\", \"subModule\"],\n});\n```\n\n```js title=\"src/index.js\"\nexport default {\n  // The value accessed through window.foo is 1\n  subModule: 1,\n};\n```\n\n## Output Filename\n\nBy 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.\n\nFor example, output a `dist/myLib.js` file:\n\n```js\nexport default {\n  output: {\n    filename: {\n      js: \"myLib.js\",\n    },\n  },\n};\n```\n\nIf you need filename hash, enable the [output.filenameHash](https://rsbuild.dev/config/output/filename-hash) option:\n\n```js\nexport default {\n  output: {\n    filenameHash: true,\n  },\n};\n```\n\n## Debugging in the Browser\n\nYou can run the `rsbuild dev` command to debug UMD outputs in the browser.\n\nFirst, create `src/index.html` and add the following code:\n\n```html title=\"src/index.html\"\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003cscript\u003e\n      console.log(window.myLib.double(1));\n    \u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nThen, specify the `template` in `rsbuild.config.ts`:\n\n```ts title=\"rsbuild.config.ts\"\nexport default {\n  plugins: [pluginUmd({ name: \"myLib\" })],\n  html: {\n    template: \"./src/index.html\",\n  },\n};\n```\n\nFinally, run `npx rsbuild dev` to start.\n\n## HTML Generation\n\nAfter 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.\n\nIf you need to generate HTML files, you can set [tools.htmlPlugin](https://rsbuild.dev/config/tools/html-plugin) to `true`:\n\n```ts title=\"rsbuild.config.ts\"\nexport default {\n  plugins: [pluginUmd({ name: \"myLib\" })],\n  html: {\n    template: \"./src/index.html\",\n  },\n  tools: {\n    htmlPlugin: true,\n  },\n};\n```\n\n## Code Splitting\n\nThe 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 `\u003cscript\u003e` tags.\n\nIf you need to split the UMD outputs, you can actively configure [performance.chunkSplit](https://rsbuild.dev/config/performance/chunk-split), for example:\n\n```js\nexport default {\n  performance: {\n    chunkSplit: {\n      strategy: \"split-by-experience\",\n    },\n  },\n};\n```\n\nNote 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`:\n\n```js\nexport default {\n  tools: {\n    rspack: {\n      output: {\n        asyncChunks: false,\n      },\n    },\n  },\n};\n```\n\n## License\n\n[MIT](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frspack-contrib%2Frsbuild-plugin-umd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frspack-contrib%2Frsbuild-plugin-umd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frspack-contrib%2Frsbuild-plugin-umd/lists"}