@babel/plugin-transform-modules-umd

Example

In

export default 42;

Out

(function (global, factory) {
  if (typeof define === "function" && define.amd) {
    define(["exports"], factory);
  } else if (typeof exports !== "undefined") {
    factory(exports);
  } else {
    var mod = {
      exports: {}
    };
    factory(mod.exports);
    global.actual = mod.exports;
  }
})(this, function (exports) {
  "use strict";
  Object.defineProperty(exports, "__esModule", {
    value: true
  });
  exports.default = 42;
});

Installation

npm install --save-dev @babel/plugin-transform-modules-umd

Usage

With a configuration file (Recommended)

{
  "plugins": ["@babel/plugin-transform-modules-umd"]
}

You can also override the names of particular libraries when this module isrunning in the browser. For example the es6-promise library exposes itselfas global.Promise rather than global.es6Promise. This can be accommodated by:

{
  "plugins": [
    ["@babel/plugin-transform-modules-umd", {
      "globals": {
        "es6-promise": "Promise"
      }
    }]
  ]
}

Default semantics

There are a few things to note about the default semantics.

First, this transform uses thebasename of each import to generatethe global names in the UMD output. This means that if you're importingmultiple modules with the same basename, like:

import fooBar1 from "foo-bar";
import fooBar2 from "./mylib/foo-bar";

it will transpile into two references to the same browser global:

factory(global.fooBar, global.fooBar);

If you set the plugin options to:

{
  "globals": {
    "foo-bar": "fooBAR",
    "./mylib/foo-bar": "mylib.fooBar"
  }
}

it will still transpile both to one browser global:

factory(global.fooBAR, global.fooBAR);

because again the transform is only using the basename of the import.

Second, the specified override will still be passed to the toIdentifierfunction in babel-types/src/converters.This means that if you specify an override as a member expression like:

{
  "globals": {
    "fizzbuzz": "fizz.buzz"
  }
}

this will not transpile to factory(global.fizz.buzz). Instead, it willtranspile to factory(global.fizzBuzz) based on the logic in toIdentifier.

Third, you cannot override the exported global name.

More flexible semantics with exactGlobals: true

All of these behaviors can limit the flexibility of the globals map. Toremove these limitations, you can set the exactGlobals option to true.Doing this instructs the plugin to:

• always use the full import string instead of the basename when generatingthe global names
• skip passing globals overrides to the toIdentifier function. Instead,they are used exactly as written, so you will get errors if you do not usevalid identifiers or valid uncomputed (dot) member expressions.
• allow the exported global name to be overridden via the globals map. Anyoverride must again be a valid identifier or valid member expression.Thus, if you set exactGlobals to true and do not pass any overrides, thefirst example of:

import fooBar1 from "foo-bar";
import fooBar2 from "./mylib/foo-bar";

will transpile to:

factory(global.fooBar, global.mylibFooBar);

And if you set the plugin options to:

{
  "globals": {
    "foo-bar": "fooBAR",
    "./mylib/foo-bar": "mylib.fooBar"
  },
  "exactGlobals": true
}

then it'll transpile to:

factory(global.fooBAR, global.mylib.fooBar)

Finally, with the plugin options set to:

{
  "plugins": [
    "@babel/plugin-external-helpers",
    ["@babel/plugin-transform-modules-umd", {
      "globals": {
        "my/custom/module/name": "My.Custom.Module.Name"
      },
      "exactGlobals": true
    }]
  ],
  "moduleId": "my/custom/module/name"
}

it will transpile to:

factory(mod.exports);
global.My = global.My || {};
global.My.Custom = global.My.Custom || {};
global.My.Custom.Module = global.My.Custom.Module || {};
global.My.Custom.Module.Name = mod.exports;

Via CLI

babel --plugins @babel/plugin-transform-modules-umd script.js

Via Node API

require("@babel/core").transform("code", {
  plugins: ["@babel/plugin-transform-modules-umd"]
});