1 | # babel-plugin-transform-es2015-modules-umd
|
2 |
|
3 | > This plugin transforms ES2015 modules to [Universal Module Definition (UMD)](https://github.com/umdjs/umd).
|
4 |
|
5 | ## Example
|
6 |
|
7 | **In**
|
8 |
|
9 | ```javascript
|
10 | export default 42;
|
11 | ```
|
12 |
|
13 | **Out**
|
14 |
|
15 | ```javascript
|
16 | (function (global, factory) {
|
17 | if (typeof define === "function" && define.amd) {
|
18 | define(["exports"], factory);
|
19 | } else if (typeof exports !== "undefined") {
|
20 | factory(exports);
|
21 | } else {
|
22 | var mod = {
|
23 | exports: {}
|
24 | };
|
25 | factory(mod.exports);
|
26 | global.actual = mod.exports;
|
27 | }
|
28 | })(this, function (exports) {
|
29 | "use strict";
|
30 |
|
31 | Object.defineProperty(exports, "__esModule", {
|
32 | value: true
|
33 | });
|
34 |
|
35 | exports.default = 42;
|
36 | });
|
37 | ```
|
38 |
|
39 | ## Installation
|
40 |
|
41 | ```sh
|
42 | npm install --save-dev babel-plugin-transform-es2015-modules-umd
|
43 | ```
|
44 |
|
45 | ## Usage
|
46 |
|
47 | ### Via `.babelrc` (Recommended)
|
48 |
|
49 | **.babelrc**
|
50 |
|
51 | ```json
|
52 | {
|
53 | "plugins": ["transform-es2015-modules-umd"]
|
54 | }
|
55 | ```
|
56 |
|
57 | You can also override the names of particular libraries when this module is
|
58 | running in the browser. For example the `es6-promise` library exposes itself
|
59 | as `global.Promise` rather than `global.es6Promise`. This can be accommodated by:
|
60 |
|
61 | ```json
|
62 | {
|
63 | "plugins": [
|
64 | ["transform-es2015-modules-umd", {
|
65 | "globals": {
|
66 | "es6-promise": "Promise"
|
67 | }
|
68 | }]
|
69 | ]
|
70 | }
|
71 | ```
|
72 |
|
73 | #### Default semantics
|
74 |
|
75 | There are a few things to note about the default semantics.
|
76 |
|
77 | _First_, this transform uses the
|
78 | [basename](https://en.wikipedia.org/wiki/Basename) of each import to generate
|
79 | the global names in the UMD output. This means that if you're importing
|
80 | multiple modules with the same basename, like:
|
81 |
|
82 | ```js
|
83 | import fooBar1 from "foo-bar";
|
84 | import fooBar2 from "./mylib/foo-bar";
|
85 | ```
|
86 |
|
87 | it will transpile into two references to the same browser global:
|
88 |
|
89 | ```js
|
90 | factory(global.fooBar, global.fooBar);
|
91 | ```
|
92 |
|
93 | If you set the plugin options to:
|
94 |
|
95 | ```json
|
96 | {
|
97 | "globals": {
|
98 | "foo-bar": "fooBAR",
|
99 | "./mylib/foo-bar": "mylib.fooBar"
|
100 | }
|
101 | }
|
102 | ```
|
103 |
|
104 | it will still transpile both to one browser global:
|
105 |
|
106 | ```js
|
107 | factory(global.fooBAR, global.fooBAR);
|
108 | ```
|
109 |
|
110 | because again the transform is only using the basename of the import.
|
111 |
|
112 | _Second_, the specified override will still be passed to the `toIdentifier`
|
113 | function in [babel-types/src/converters](https://github.com/babel/babel/blob/master/packages/babel-types/src/converters.js).
|
114 | This means that if you specify an override as a member expression like:
|
115 |
|
116 | ```json
|
117 | {
|
118 | "globals": {
|
119 | "fizzbuzz": "fizz.buzz"
|
120 | }
|
121 | }
|
122 | ```
|
123 |
|
124 | this will _not_ transpile to `factory(global.fizz.buzz)`. Instead, it will
|
125 | transpile to `factory(global.fizzBuzz)` based on the logic in `toIdentifier`.
|
126 |
|
127 | _Third_, you cannot override the exported global name.
|
128 |
|
129 | #### More flexible semantics with `exactGlobals: true`
|
130 |
|
131 | All of these behaviors can limit the flexibility of the `globals` map. To
|
132 | remove these limitations, you can set the `exactGlobals` option to `true`.
|
133 | Doing this instructs the plugin to:
|
134 |
|
135 | 1. always use the full import string instead of the basename when generating
|
136 | the global names
|
137 | 2. skip passing `globals` overrides to the `toIdentifier` function. Instead,
|
138 | they are used exactly as written, so you will get errors if you do not use
|
139 | valid identifiers or valid uncomputed (dot) member expressions.
|
140 | 3. allow the exported global name to be overridden via the `globals` map. Any
|
141 | override must again be a valid identifier or valid member expression.
|
142 |
|
143 | Thus, if you set `exactGlobals` to `true` and do not pass any overrides, the
|
144 | first example of:
|
145 |
|
146 | ```js
|
147 | import fooBar1 from "foo-bar";
|
148 | import fooBar2 from "./mylib/foo-bar";
|
149 | ```
|
150 |
|
151 | will transpile to:
|
152 |
|
153 | ```js
|
154 | factory(global.fooBar, global.mylibFooBar);
|
155 | ```
|
156 |
|
157 | And if you set the plugin options to:
|
158 |
|
159 | ```json
|
160 | {
|
161 | "globals": {
|
162 | "foo-bar": "fooBAR",
|
163 | "./mylib/foo-bar": "mylib.fooBar"
|
164 | },
|
165 | "exactGlobals": true
|
166 | }
|
167 | ```
|
168 |
|
169 | then it'll transpile to:
|
170 |
|
171 | ```js
|
172 | factory(global.fooBAR, global.mylib.fooBar)
|
173 | ```
|
174 |
|
175 | Finally, with the plugin options set to:
|
176 |
|
177 | ```json
|
178 | {
|
179 | "plugins": [
|
180 | "external-helpers",
|
181 | ["transform-es2015-modules-umd", {
|
182 | "globals": {
|
183 | "my/custom/module/name": "My.Custom.Module.Name"
|
184 | },
|
185 | "exactGlobals": true
|
186 | }]
|
187 | ],
|
188 | "moduleId": "my/custom/module/name"
|
189 | }
|
190 | ```
|
191 |
|
192 | it will transpile to:
|
193 |
|
194 | ```js
|
195 | factory(mod.exports);
|
196 | global.My = global.My || {};
|
197 | global.My.Custom = global.My.Custom || {};
|
198 | global.My.Custom.Module = global.My.Custom.Module || {};
|
199 | global.My.Custom.Module.Name = mod.exports;
|
200 | ```
|
201 |
|
202 | ### Via CLI
|
203 |
|
204 | ```sh
|
205 | babel --plugins transform-es2015-modules-umd script.js
|
206 | ```
|
207 |
|
208 | ### Via Node API
|
209 |
|
210 | ```javascript
|
211 | require("babel-core").transform("code", {
|
212 | plugins: ["transform-es2015-modules-umd"]
|
213 | });
|
214 | ```
|