esbuild-plugin-umd-wrapper

3.0.0 verified Mon Apr 27 auth: no javascript

An esbuild plugin that wraps bundled JavaScript output into UMD format, supporting AMD, CommonJS, and global variable exports. Version 3.0.0 is the latest stable release, actively maintained. It integrates seamlessly with esbuild's build pipeline, automatically adjusting the format to CJS before wrapping. Key differentiators: lightweight, zero-config, and compatible with esbuild's build options. It includes TypeScript declarations and allows customization of library name and wrapper options. Works with esbuild 0.8+.

Common errors

error Error: The plugin "umd-wrapper" must be used with esbuild format "cjs" or "umd". ↓

cause esbuild format not set to 'cjs' or 'umd'.

fix

Set format: 'umd' or format: 'cjs' in esbuild build options.

error TypeError: umdWrapper is not a function ↓

cause Incorrect import: default import used instead of named import.

fix

Use import { umdWrapper } from 'esbuild-plugin-umd-wrapper' or const { umdWrapper } = require('esbuild-plugin-umd-wrapper').

error Cannot find module 'esbuild-plugin-umd-wrapper' ↓

cause Package not installed or Node.js resolution issue.

fix

Run npm install -D esbuild-plugin-umd-wrapper or yarn add -D esbuild-plugin-umd-wrapper.

Warnings

gotcha When export default is used, the output is not directly callable; it becomes an object with __esModule and default property. ↓

fix Use module.exports = myFunc or exports = myFunc instead of export default.

gotcha Concurrent esbuild builds reusing the same options object reference may produce unexpected output because the plugin modifies banner/footer on the options object. ↓

fix Avoid running esbuild.build calls concurrently that share the same options object. Use sequential builds or deep clone the options.

breaking Version 3.0.0 changed internal behavior: plugin now forces format to 'cjs' before executing, which may affect plugins that rely on format being 'umd' during build. ↓

fix If you need the format to remain 'umd' for other plugins, update your build pipeline accordingly. The plugin will still produce UMD output.

Install

npm install esbuild-plugin-umd-wrapper

yarn add esbuild-plugin-umd-wrapper

pnpm add esbuild-plugin-umd-wrapper

Imports

umdWrapper

wrong

import umdWrapper from 'esbuild-plugin-umd-wrapper'

correct

import { umdWrapper } from 'esbuild-plugin-umd-wrapper'

Named export, not default. TypeScript included.

umdWrapper

wrong

const umdWrapper = require('esbuild-plugin-umd-wrapper')

correct

const { umdWrapper } = require('esbuild-plugin-umd-wrapper')

CommonJS destructure required.

UmbrellaOptions

import type { UmbrellaOptions } from 'esbuild-plugin-umd-wrapper'

Type import for options interface.

Quickstart

Uses esbuild-plugin-umd-wrapper to bundle 'src/index.js' into UMD format with a custom library name 'MyLib'.

const esbuild = require('esbuild');
const { umdWrapper } = require('esbuild-plugin-umd-wrapper');

esbuild.build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  bundle: true,
  format: 'umd', // plugin will override to 'cjs' internally
  plugins: [umdWrapper({ libraryName: 'MyLib' })],
}).then(result => console.log(result))
  .catch(() => process.exit(1));