esm2umd

Transforms ESM to UMD, i.e. to use ESM by default with UMD as a legacy fallback.

Usage

$> npm install --save-dev esm2umd

npx esm2umd MyModule esmFile.js > umdFile.js

MyModule is used as the name of the vanilla JS global.

If the module has a default export, it is transformed to a whole-module export.

API

import esm2umd from "esm2umd";

const esmCode = "...";
const umdCode = esm2umd("ModuleName", esmCode);

Examples

Common outline of a hybrid module with legacy fallback, either exporting a class or a namespace:

package.json

{
  "type": "module",
  "main": "./umd/index.js",
  "types": "./umd/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./index.d.ts",
        "default": "./index.js"
      },
      "require": {
        "types": "./umd/index.d.ts",
        "default": "./umd/index.js"
      }
    }
  },
  "scripts": {
    "build": "npx esm2umd MyModule index.js > umd/index.js && cp types.d.ts umd/types.d.ts"
  }
}

umd/package.json

{
  "type": "commonjs"
}

.gitignore

umd/index.js
umd/types.d.ts

Class export

As used by long.js:

index.d.ts

import { MyClass } from "./types.js";
export default MyClass;

types.d.ts

export declare class MyClass {
  // ...
}

umd/index.d.ts

import { MyClass } from "./types.js";
export = MyClass;
export as namespace MyClass;

umd/types.d.ts

Copy of types.d.ts.

Namespace export

As used by bcrypt.js:

index.d.ts

import * as myNamespace from "./types.js";
export * from "./types.js";
export default myNamespace;

types.d.ts

export declare function myFunction(): void;
// ...

umd/index.d.ts

import * as myNamespace from "./types.js";
export = myNamespace;
export as namespace myNamespace;

umd/types.d.ts

Copy of types.d.ts.

Building

Building the UMD fallback:

$> npm run build

Running the tests:

$> npm test