Merge pull request #3534 from rmacklin/add-exactGlobals-option-to-umd-transform
Add exactGlobals option to transform-es2015-modules-umd plugin to enable more flexibility in specifying global names
This commit is contained in:
Logan Smyth
GitHub
commit
81f0f464e7
@ -20,9 +20,9 @@ $ npm install babel-plugin-transform-es2015-modules-umd
|
||||
|
||||
You can also override the names of particular libraries when this module is
|
||||
running in the browser. For example the `es6-promise` library exposes itself
|
||||
as `global.Promise` rather than `global.es6Promise`. This can be accomidated by:
|
||||
as `global.Promise` rather than `global.es6Promise`. This can be accommodated by:
|
||||
|
||||
```
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
["transform-es2015-modules-umd", {
|
||||
@ -34,6 +34,135 @@ as `global.Promise` rather than `global.es6Promise`. This can be accomidated by:
|
||||
}
|
||||
```
|
||||
|
||||
#### Default semantics
|
||||
|
||||
There are a few things to note about the default semantics.
|
||||
|
||||
_First_, this transform uses the
|
||||
[basename](https://en.wikipedia.org/wiki/Basename) of each import to generate
|
||||
the global names in the UMD output. This means that if you're importing
|
||||
multiple modules with the same basename, like:
|
||||
|
||||
```js
|
||||
import fooBar1 from "foo-bar";
|
||||
import fooBar2 from "./mylib/foo-bar";
|
||||
```
|
||||
|
||||
it will transpile into two references to the same browser global:
|
||||
|
||||
```js
|
||||
factory(global.fooBar, global.fooBar);
|
||||
```
|
||||
|
||||
If you set the plugin options to:
|
||||
|
||||
```json
|
||||
{
|
||||
"globals": {
|
||||
"foo-bar": "fooBAR",
|
||||
"./mylib/foo-bar": "mylib.fooBar"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
it will still transpile both to one browser global:
|
||||
|
||||
```js
|
||||
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 `toIdentifier`
|
||||
function in [babel-types/src/converters](../babel-types/src/converters.js).
|
||||
This means that if you specify an override as a member expression like:
|
||||
|
||||
```json
|
||||
{
|
||||
"globals": {
|
||||
"fizzbuzz": "fizz.buzz"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
this will _not_ transpile to `factory(global.fizz.buzz)`. Instead, it will
|
||||
transpile 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. To
|
||||
remove these limitations, you can set the `exactGlobals` option to `true`.
|
||||
Doing this instructs the plugin to:
|
||||
|
||||
1. always use the full import string instead of the basename when generating
|
||||
the global names
|
||||
2. skip passing `globals` overrides to the `toIdentifier` function. Instead,
|
||||
they are used exactly as written, so you will get errors if you do not use
|
||||
valid identifiers or valid uncomputed (dot) member expressions.
|
||||
3. allow the exported global name to be overridden via the `globals` map. Any
|
||||
override must again be a valid identifier or valid member expression.
|
||||
|
||||
Thus, if you set `exactGlobals` to `true` and do not pass any overrides, the
|
||||
first example of:
|
||||
|
||||
```js
|
||||
import fooBar1 from "foo-bar";
|
||||
import fooBar2 from "./mylib/foo-bar";
|
||||
```
|
||||
|
||||
will transpile to:
|
||||
|
||||
```js
|
||||
factory(global.fooBar, global.mylibFooBar);
|
||||
```
|
||||
|
||||
And if you set the plugin options to:
|
||||
|
||||
```json
|
||||
{
|
||||
"globals": {
|
||||
"foo-bar": "fooBAR",
|
||||
"./mylib/foo-bar": "mylib.fooBar"
|
||||
},
|
||||
"exactGlobals": true
|
||||
}
|
||||
```
|
||||
|
||||
then it'll transpile to:
|
||||
|
||||
```js
|
||||
factory(global.fooBAR, global.mylib.fooBar)
|
||||
```
|
||||
|
||||
Finally, with the plugin options set to:
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
"external-helpers",
|
||||
["transform-es2015-modules-umd", {
|
||||
"globals": {
|
||||
"my/custom/module/name": "My.Custom.Module.Name"
|
||||
},
|
||||
"exactGlobals": true
|
||||
}]
|
||||
],
|
||||
"moduleId": "my/custom/module/name"
|
||||
}
|
||||
```
|
||||
|
||||
it will transpile to:
|
||||
|
||||
```js
|
||||
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
|
||||
|
||||
```sh
|
||||
|
||||
@ -3,6 +3,17 @@
|
||||
import { basename, extname } from "path";
|
||||
import template from "babel-template";
|
||||
|
||||
let buildPrerequisiteAssignment = template(`
|
||||
GLOBAL_REFERENCE = GLOBAL_REFERENCE || {}
|
||||
`);
|
||||
|
||||
let buildGlobalExport = template(`
|
||||
var mod = { exports: {} };
|
||||
factory(BROWSER_ARGUMENTS);
|
||||
PREREQUISITE_ASSIGNMENTS
|
||||
GLOBAL_TO_ASSIGN = mod.exports;
|
||||
`);
|
||||
|
||||
let buildWrapper = template(`
|
||||
(function (global, factory) {
|
||||
if (typeof define === "function" && define.amd) {
|
||||
@ -10,9 +21,7 @@ let buildWrapper = template(`
|
||||
} else if (typeof exports !== "undefined") {
|
||||
factory(COMMON_ARGUMENTS);
|
||||
} else {
|
||||
var mod = { exports: {} };
|
||||
factory(BROWSER_ARGUMENTS);
|
||||
global.GLOBAL_ARG = mod.exports;
|
||||
GLOBAL_EXPORT
|
||||
}
|
||||
})(this, FUNC);
|
||||
`);
|
||||
@ -65,23 +74,62 @@ export default function ({ types: t }) {
|
||||
} else if (arg.value === "exports") {
|
||||
return t.memberExpression(t.identifier("mod"), t.identifier("exports"));
|
||||
} else {
|
||||
let requireName = basename(arg.value, extname(arg.value));
|
||||
let globalName = browserGlobals[requireName] || requireName;
|
||||
let memberExpression;
|
||||
|
||||
return t.memberExpression(t.identifier("global"), t.identifier(
|
||||
t.toIdentifier(globalName)
|
||||
));
|
||||
if (state.opts.exactGlobals) {
|
||||
let globalRef = browserGlobals[arg.value];
|
||||
if (globalRef) {
|
||||
memberExpression = globalRef.split(".").reduce(
|
||||
(accum, curr) => t.memberExpression(accum, t.identifier(curr)), t.identifier("global")
|
||||
);
|
||||
} else {
|
||||
memberExpression = t.memberExpression(
|
||||
t.identifier("global"), t.identifier(t.toIdentifier(arg.value))
|
||||
);
|
||||
}
|
||||
} else {
|
||||
let requireName = basename(arg.value, extname(arg.value));
|
||||
let globalName = browserGlobals[requireName] || requireName;
|
||||
memberExpression = t.memberExpression(
|
||||
t.identifier("global"), t.identifier(t.toIdentifier(globalName))
|
||||
);
|
||||
}
|
||||
|
||||
return memberExpression;
|
||||
}
|
||||
});
|
||||
|
||||
let globalArg = t.identifier(t.toIdentifier(moduleName ? moduleName.value : this.file.opts.basename));
|
||||
let moduleNameOrBasename = moduleName ? moduleName.value : this.file.opts.basename;
|
||||
let globalToAssign = t.memberExpression(
|
||||
t.identifier("global"), t.identifier(t.toIdentifier(moduleNameOrBasename))
|
||||
);
|
||||
let prerequisiteAssignments = null;
|
||||
|
||||
if (state.opts.exactGlobals) {
|
||||
let globalName = browserGlobals[moduleNameOrBasename];
|
||||
|
||||
if (globalName) {
|
||||
prerequisiteAssignments = [];
|
||||
|
||||
let members = globalName.split(".");
|
||||
globalToAssign = members.slice(1).reduce((accum, curr) => {
|
||||
prerequisiteAssignments.push(buildPrerequisiteAssignment({ GLOBAL_REFERENCE: accum }));
|
||||
return t.memberExpression(accum, t.identifier(curr));
|
||||
}, t.memberExpression(t.identifier("global"), t.identifier(members[0])));
|
||||
}
|
||||
}
|
||||
|
||||
let globalExport = buildGlobalExport({
|
||||
BROWSER_ARGUMENTS: browserArgs,
|
||||
PREREQUISITE_ASSIGNMENTS: prerequisiteAssignments,
|
||||
GLOBAL_TO_ASSIGN: globalToAssign
|
||||
});
|
||||
|
||||
last.replaceWith(buildWrapper({
|
||||
MODULE_NAME: moduleName,
|
||||
BROWSER_ARGUMENTS: browserArgs,
|
||||
AMD_ARGUMENTS: amdArgs,
|
||||
COMMON_ARGUMENTS: commonArgs,
|
||||
GLOBAL_ARG: globalArg,
|
||||
GLOBAL_EXPORT: globalExport,
|
||||
FUNC: func
|
||||
}));
|
||||
}
|
||||
|
||||
@ -0,0 +1,3 @@
|
||||
import fooBar1 from "foo-bar";
|
||||
import fooBar2 from "./mylib/foo-bar";
|
||||
import fizzBuzz from "fizzbuzz";
|
||||
@ -0,0 +1,21 @@
|
||||
(function (global, factory) {
|
||||
if (typeof define === "function" && define.amd) {
|
||||
define(["foo-bar", "./mylib/foo-bar", "fizzbuzz"], factory);
|
||||
} else if (typeof exports !== "undefined") {
|
||||
factory(require("foo-bar"), require("./mylib/foo-bar"), require("fizzbuzz"));
|
||||
} else {
|
||||
var mod = {
|
||||
exports: {}
|
||||
};
|
||||
factory(global.fooBAR, global.fooBAR, global.fizzBuzz);
|
||||
global.actual = mod.exports;
|
||||
}
|
||||
})(this, function (_fooBar, _fooBar3, _fizzbuzz) {
|
||||
"use strict";
|
||||
|
||||
var _fooBar2 = babelHelpers.interopRequireDefault(_fooBar);
|
||||
|
||||
var _fooBar4 = babelHelpers.interopRequireDefault(_fooBar3);
|
||||
|
||||
var _fizzbuzz2 = babelHelpers.interopRequireDefault(_fizzbuzz);
|
||||
});
|
||||
@ -0,0 +1,12 @@
|
||||
{
|
||||
"plugins": [
|
||||
"external-helpers",
|
||||
["transform-es2015-modules-umd", {
|
||||
"globals": {
|
||||
"foo-bar": "fooBAR",
|
||||
"./mylib/foo-bar": "mylib.fooBar",
|
||||
"fizzbuzz": "fizz.buzz"
|
||||
}
|
||||
}]
|
||||
]
|
||||
}
|
||||
@ -0,0 +1,3 @@
|
||||
import fooBar1 from "foo-bar";
|
||||
import fooBar2 from "./mylib/foo-bar";
|
||||
import fizzBuzz from "fizzbuzz";
|
||||
@ -0,0 +1,21 @@
|
||||
(function (global, factory) {
|
||||
if (typeof define === "function" && define.amd) {
|
||||
define(["foo-bar", "./mylib/foo-bar", "fizzbuzz"], factory);
|
||||
} else if (typeof exports !== "undefined") {
|
||||
factory(require("foo-bar"), require("./mylib/foo-bar"), require("fizzbuzz"));
|
||||
} else {
|
||||
var mod = {
|
||||
exports: {}
|
||||
};
|
||||
factory(global.fooBar, global.fooBar, global.fizzbuzz);
|
||||
global.actual = mod.exports;
|
||||
}
|
||||
})(this, function (_fooBar, _fooBar3, _fizzbuzz) {
|
||||
"use strict";
|
||||
|
||||
var _fooBar2 = babelHelpers.interopRequireDefault(_fooBar);
|
||||
|
||||
var _fooBar4 = babelHelpers.interopRequireDefault(_fooBar3);
|
||||
|
||||
var _fizzbuzz2 = babelHelpers.interopRequireDefault(_fizzbuzz);
|
||||
});
|
||||
@ -0,0 +1,3 @@
|
||||
import fooBar1 from "foo-bar";
|
||||
import fooBar2 from "./mylib/foo-bar";
|
||||
import fizzBuzz from "fizzbuzz";
|
||||
@ -0,0 +1,21 @@
|
||||
(function (global, factory) {
|
||||
if (typeof define === "function" && define.amd) {
|
||||
define(["foo-bar", "./mylib/foo-bar", "fizzbuzz"], factory);
|
||||
} else if (typeof exports !== "undefined") {
|
||||
factory(require("foo-bar"), require("./mylib/foo-bar"), require("fizzbuzz"));
|
||||
} else {
|
||||
var mod = {
|
||||
exports: {}
|
||||
};
|
||||
factory(global.fooBAR, global.mylib.fooBar, global.fizz.buzz);
|
||||
global.actual = mod.exports;
|
||||
}
|
||||
})(this, function (_fooBar, _fooBar3, _fizzbuzz) {
|
||||
"use strict";
|
||||
|
||||
var _fooBar2 = babelHelpers.interopRequireDefault(_fooBar);
|
||||
|
||||
var _fooBar4 = babelHelpers.interopRequireDefault(_fooBar3);
|
||||
|
||||
var _fizzbuzz2 = babelHelpers.interopRequireDefault(_fizzbuzz);
|
||||
});
|
||||
@ -0,0 +1,13 @@
|
||||
{
|
||||
"plugins": [
|
||||
"external-helpers",
|
||||
["transform-es2015-modules-umd", {
|
||||
"globals": {
|
||||
"foo-bar": "fooBAR",
|
||||
"./mylib/foo-bar": "mylib.fooBar",
|
||||
"fizzbuzz": "fizz.buzz"
|
||||
},
|
||||
"exactGlobals": true
|
||||
}]
|
||||
]
|
||||
}
|
||||
@ -0,0 +1,3 @@
|
||||
import fooBar1 from "foo-bar";
|
||||
import fooBar2 from "./mylib/foo-bar";
|
||||
import fizzBuzz from "fizzbuzz";
|
||||
@ -0,0 +1,21 @@
|
||||
(function (global, factory) {
|
||||
if (typeof define === "function" && define.amd) {
|
||||
define(["foo-bar", "./mylib/foo-bar", "fizzbuzz"], factory);
|
||||
} else if (typeof exports !== "undefined") {
|
||||
factory(require("foo-bar"), require("./mylib/foo-bar"), require("fizzbuzz"));
|
||||
} else {
|
||||
var mod = {
|
||||
exports: {}
|
||||
};
|
||||
factory(global.fooBar, global.mylibFooBar, global.fizzbuzz);
|
||||
global.actual = mod.exports;
|
||||
}
|
||||
})(this, function (_fooBar, _fooBar3, _fizzbuzz) {
|
||||
"use strict";
|
||||
|
||||
var _fooBar2 = babelHelpers.interopRequireDefault(_fooBar);
|
||||
|
||||
var _fooBar4 = babelHelpers.interopRequireDefault(_fooBar3);
|
||||
|
||||
var _fizzbuzz2 = babelHelpers.interopRequireDefault(_fizzbuzz);
|
||||
});
|
||||
@ -0,0 +1,8 @@
|
||||
{
|
||||
"plugins": [
|
||||
"external-helpers",
|
||||
["transform-es2015-modules-umd", {
|
||||
"exactGlobals": true
|
||||
}]
|
||||
]
|
||||
}
|
||||
@ -0,0 +1 @@
|
||||
export default 42;
|
||||
@ -0,0 +1,21 @@
|
||||
(function (global, factory) {
|
||||
if (typeof define === "function" && define.amd) {
|
||||
define("my custom module name", ["exports"], factory);
|
||||
} else if (typeof exports !== "undefined") {
|
||||
factory(exports);
|
||||
} else {
|
||||
var mod = {
|
||||
exports: {}
|
||||
};
|
||||
factory(mod.exports);
|
||||
global.foo = global.foo || {};
|
||||
global.foo.bar = mod.exports;
|
||||
}
|
||||
})(this, function (exports) {
|
||||
"use strict";
|
||||
|
||||
Object.defineProperty(exports, "__esModule", {
|
||||
value: true
|
||||
});
|
||||
exports.default = 42;
|
||||
});
|
||||
@ -0,0 +1,12 @@
|
||||
{
|
||||
"plugins": [
|
||||
"external-helpers",
|
||||
["transform-es2015-modules-umd", {
|
||||
"globals": {
|
||||
"my custom module name": "foo.bar"
|
||||
},
|
||||
"exactGlobals": true
|
||||
}]
|
||||
],
|
||||
"moduleId": "my custom module name"
|
||||
}
|
||||
@ -0,0 +1 @@
|
||||
export default 42;
|
||||
@ -0,0 +1,23 @@
|
||||
(function (global, factory) {
|
||||
if (typeof define === "function" && define.amd) {
|
||||
define("my custom module name", ["exports"], factory);
|
||||
} else if (typeof exports !== "undefined") {
|
||||
factory(exports);
|
||||
} else {
|
||||
var mod = {
|
||||
exports: {}
|
||||
};
|
||||
factory(mod.exports);
|
||||
global.foo = global.foo || {};
|
||||
global.foo.bar = global.foo.bar || {};
|
||||
global.foo.bar.baz = global.foo.bar.baz || {};
|
||||
global.foo.bar.baz.qux = mod.exports;
|
||||
}
|
||||
})(this, function (exports) {
|
||||
"use strict";
|
||||
|
||||
Object.defineProperty(exports, "__esModule", {
|
||||
value: true
|
||||
});
|
||||
exports.default = 42;
|
||||
});
|
||||
@ -0,0 +1,12 @@
|
||||
{
|
||||
"plugins": [
|
||||
"external-helpers",
|
||||
["transform-es2015-modules-umd", {
|
||||
"globals": {
|
||||
"my custom module name": "foo.bar.baz.qux"
|
||||
},
|
||||
"exactGlobals": true
|
||||
}]
|
||||
],
|
||||
"moduleId": "my custom module name"
|
||||
}
|
||||
@ -0,0 +1 @@
|
||||
export default 42;
|
||||
@ -0,0 +1,20 @@
|
||||
(function (global, factory) {
|
||||
if (typeof define === "function" && define.amd) {
|
||||
define("my custom module name", ["exports"], factory);
|
||||
} else if (typeof exports !== "undefined") {
|
||||
factory(exports);
|
||||
} else {
|
||||
var mod = {
|
||||
exports: {}
|
||||
};
|
||||
factory(mod.exports);
|
||||
global.baz = mod.exports;
|
||||
}
|
||||
})(this, function (exports) {
|
||||
"use strict";
|
||||
|
||||
Object.defineProperty(exports, "__esModule", {
|
||||
value: true
|
||||
});
|
||||
exports.default = 42;
|
||||
});
|
||||
@ -0,0 +1,12 @@
|
||||
{
|
||||
"plugins": [
|
||||
"external-helpers",
|
||||
["transform-es2015-modules-umd", {
|
||||
"globals": {
|
||||
"my custom module name": "baz"
|
||||
},
|
||||
"exactGlobals": true
|
||||
}]
|
||||
],
|
||||
"moduleId": "my custom module name"
|
||||
}
|
||||
@ -0,0 +1 @@
|
||||
export default 42;
|
||||
@ -0,0 +1,20 @@
|
||||
(function (global, factory) {
|
||||
if (typeof define === "function" && define.amd) {
|
||||
define("umd/module-name-with-overridden-global/expected", ["exports"], factory);
|
||||
} else if (typeof exports !== "undefined") {
|
||||
factory(exports);
|
||||
} else {
|
||||
var mod = {
|
||||
exports: {}
|
||||
};
|
||||
factory(mod.exports);
|
||||
global.baz = mod.exports;
|
||||
}
|
||||
})(this, function (exports) {
|
||||
"use strict";
|
||||
|
||||
Object.defineProperty(exports, "__esModule", {
|
||||
value: true
|
||||
});
|
||||
exports.default = 42;
|
||||
});
|
||||
@ -0,0 +1,12 @@
|
||||
{
|
||||
"plugins": [
|
||||
"external-helpers",
|
||||
["transform-es2015-modules-umd", {
|
||||
"globals": {
|
||||
"umd/module-name-with-overridden-global/expected": "baz"
|
||||
},
|
||||
"exactGlobals": true
|
||||
}]
|
||||
],
|
||||
"moduleIds": true
|
||||
}
|
||||
@ -0,0 +1 @@
|
||||
export default 42;
|
||||
@ -0,0 +1,20 @@
|
||||
(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.baz = mod.exports;
|
||||
}
|
||||
})(this, function (exports) {
|
||||
"use strict";
|
||||
|
||||
Object.defineProperty(exports, "__esModule", {
|
||||
value: true
|
||||
});
|
||||
exports.default = 42;
|
||||
});
|
||||
@ -0,0 +1,11 @@
|
||||
{
|
||||
"plugins": [
|
||||
"external-helpers",
|
||||
["transform-es2015-modules-umd", {
|
||||
"globals": {
|
||||
"actual": "baz"
|
||||
},
|
||||
"exactGlobals": true
|
||||
}]
|
||||
]
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user