Skip to content

Latest commit

 

History

History
212 lines (157 loc) · 5.09 KB

README.md

File metadata and controls

212 lines (157 loc) · 5.09 KB
Raw

@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.

npm version license

Usage

Install:

npm add @rsbuild/plugin-umd -D

Add 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)); // -> 2

Options

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 export is configured as default, accessing window.foo will give you the content exported by export 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.