https://github.com/inqnuam/esbuild-plugin-umd-wrapper
UMD wrapper for esbuild
https://github.com/inqnuam/esbuild-plugin-umd-wrapper
Last synced: 3 months ago
JSON representation
UMD wrapper for esbuild
- Host: GitHub
- URL: https://github.com/inqnuam/esbuild-plugin-umd-wrapper
- Owner: Inqnuam
- Created: 2022-12-13T18:09:38.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-22T11:00:16.000Z (11 months ago)
- Last Synced: 2025-03-10T20:47:16.948Z (3 months ago)
- Language: TypeScript
- Size: 60.5 KB
- Stars: 19
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## Description
> An esbuild plugin to wrap your js into UMD format.
# Installation
```bash
yarn add -D esbuild-plugin-umd-wrapper
# or
npm install -D esbuild-plugin-umd-wrapper
```
## Usage
```js
const esbuild = require("esbuild");
const { umdWrapper } = require("esbuild-plugin-umd-wrapper");
esbuild
.build({
entryPoints: ["src/input.js"],
outdir: "dist",
bundle: true,
format: "umd", // or "cjs"
plugins: [umdWrapper()],
})
.then((result) => console.log(result))
.catch(() => process.exit(1));
```
### Customize the wrapper.
See [all options](https://github.com/Inqnuam/esbuild-plugin-umd-wrapper/blob/main/src/declaration.ts).
```js
esbuild.build({
entryPoints: ["src/input.js"],
outdir: "dist",
bundle: true,
format: "umd", // or "cjs"
plugins: [umdWrapper({ libraryName: "myLibrary" })],
});
```
Wrapper options will be applied for all `entryPoints`.
---
## Notes
The plugin will be triggered only if esbuild `format` is set to "cjs" or "umd".
Before esbuild execution the plugin will set that option to "cjs".
## Known Issues
Internally the wrapper plugin uses esbuild's `banner` and `footer` options to create UMD.
In consequence running multiple esbuild builds concurrently reusing the same Build option object references _MAY_ produce unexpected build output
Ex:
```js
const options = {
entryPoints: ["src/input.js"],
outdir: "dist",
bundle: true,
format: "umd",
plugins: [umdWrapper({ libraryName: "myLibrary" })],
};
// ❌ avoid this
await Promise.all([esbuild.build(options), esbuild.build({ ...options, minify: true, outdir: "dist/min" })]);
```
```js
// ❌ avoid this
esbuild.build(options);
esbuild.build({ ...options, minify: true, outdir: "dist/min" });
```
```js
// ✅ Its better
await esbuild.build(options);
await esbuild.build({ ...options, minify: true, outdir: "dist/min" });
```
---
> When I use `export default myFunc`, resulting output is not directly callable!
> Instead it's an object `{__esModule: true, default: myFunc}`
This is not a bug, and it's not related to umd-wrapper-plugin.
This is how esbuild transpiles `export default` to CJS.
As a workaround use `exports = myFunc`.
---
### Examples
If you are not familiar with UMD, see usage examples in [test](test) directory.