1 | <div align="center">
|
2 | <a href="https://github.com/webpack/webpack">
|
3 | <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
|
4 | </a>
|
5 | </div>
|
6 |
|
7 | [![npm][npm]][npm-url]
|
8 | [![node][node]][node-url]
|
9 | [![deps][deps]][deps-url]
|
10 | [![tests][tests]][tests-url]
|
11 | [![coverage][cover]][cover-url]
|
12 | [![chat][chat]][chat-url]
|
13 | [![size][size]][size-url]
|
14 |
|
15 | # expose-loader
|
16 |
|
17 | The `expose-loader` loader allows to expose a module (in whole or in part) to global object (`self`, `window` and `global`).
|
18 |
|
19 | For further hints on compatibility issues, check out [Shimming](https://webpack.js.org/guides/shimming/) of the official docs.
|
20 |
|
21 | ## Getting Started
|
22 |
|
23 | To begin, you'll need to install `expose-loader`:
|
24 |
|
25 | ```console
|
26 | npm install expose-loader --save-dev
|
27 | ```
|
28 |
|
29 | or
|
30 |
|
31 | ```console
|
32 | yarn add -D expose-loader
|
33 | ```
|
34 |
|
35 | or
|
36 |
|
37 | ```console
|
38 | pnpm -D expose-loader
|
39 | ```
|
40 |
|
41 | (If you're using WebPack 4, install `expose-loader@1` and follow the [corresponding instructions](https://v4.webpack.js.org/loaders/expose-loader/) instead.)
|
42 |
|
43 | Then you can use the `expose-loader` using two approaches.
|
44 |
|
45 | ## Inline
|
46 |
|
47 | The `|` or `%20` (space) allow to separate the `globalName`, `moduleLocalName` and `override` of expose.
|
48 | The documentation and syntax examples can be read [here](#syntax).
|
49 |
|
50 | > ⚠ `%20` is space in a query string, because you can't use spaces in URLs
|
51 |
|
52 | ```js
|
53 | import $ from "expose-loader?exposes=$,jQuery!jquery";
|
54 | //
|
55 | // Adds the `jquery` to the global object under the names `$` and `jQuery`
|
56 | ```
|
57 |
|
58 | ```js
|
59 | import { concat } from "expose-loader?exposes=_.concat!lodash/concat";
|
60 | //
|
61 | // Adds the `lodash/concat` to the global object under the name `_.concat`
|
62 | ```
|
63 |
|
64 | ```js
|
65 | import {
|
66 | map,
|
67 | reduce,
|
68 | } from "expose-loader?exposes=_.map|map,_.reduce|reduce!underscore";
|
69 | //
|
70 | // Adds the `map` and `reduce` method from `underscore` to the global object under the name `_.map` and `_.reduce`
|
71 | ```
|
72 |
|
73 | ## Using Configuration
|
74 |
|
75 | **src/index.js**
|
76 |
|
77 | ```js
|
78 | import $ from "jquery";
|
79 | ```
|
80 |
|
81 | **webpack.config.js**
|
82 |
|
83 | ```js
|
84 | module.exports = {
|
85 | module: {
|
86 | rules: [
|
87 | {
|
88 | test: require.resolve("jquery"),
|
89 | loader: "expose-loader",
|
90 | options: {
|
91 | exposes: ["$", "jQuery"],
|
92 | },
|
93 | },
|
94 | {
|
95 | test: require.resolve("underscore"),
|
96 | loader: "expose-loader",
|
97 | options: {
|
98 | exposes: [
|
99 | "_.map|map",
|
100 | {
|
101 | globalName: "_.reduce",
|
102 | moduleLocalName: "reduce",
|
103 | },
|
104 | {
|
105 | globalName: ["_", "filter"],
|
106 | moduleLocalName: "filter",
|
107 | },
|
108 | ],
|
109 | },
|
110 | },
|
111 | ],
|
112 | },
|
113 | };
|
114 | ```
|
115 |
|
116 | The [`require.resolve`](https://nodejs.org/api/modules.html#modules_require_resolve_request_options) call is a Node.js function (unrelated to `require.resolve` in webpack processing).
|
117 | `require.resolve` gives you the absolute path to the module (`"/.../app/node_modules/jquery/dist/jquery.js"`).
|
118 | So the expose only applies to the `jquery` module. And it's only exposed when used in the bundle.
|
119 |
|
120 | And run `webpack` via your preferred method.
|
121 |
|
122 | ## Options
|
123 |
|
124 | | Name | Type | Default | Description |
|
125 | | :-----------------------: | :---------------------------------------: | :---------: | :-------------- |
|
126 | | **[`exposes`](#exposes)** | `{String\|Object\|Array<String\|Object>}` | `undefined` | List of exposes |
|
127 |
|
128 | ### `exposes`
|
129 |
|
130 | Type:
|
131 |
|
132 | ```ts
|
133 | type exposes =
|
134 | | string
|
135 | | {
|
136 | globalName: string | Array<string>;
|
137 | moduleLocalName?: string;
|
138 | override?: boolean;
|
139 | }
|
140 | | Array<
|
141 | | string
|
142 | | {
|
143 | globalName: string | Array<string>;
|
144 | moduleLocalName?: string;
|
145 | override?: boolean;
|
146 | }
|
147 | >;
|
148 | ```
|
149 |
|
150 | Default: `undefined`
|
151 |
|
152 | List of exposes.
|
153 |
|
154 | #### `string`
|
155 |
|
156 | Allows to use a string to describe an expose.
|
157 |
|
158 | ##### `syntax`
|
159 |
|
160 | The `|` or `%20` (space) allow to separate the `globalName`, `moduleLocalName` and `override` of expose.
|
161 |
|
162 | String syntax - `[[globalName] [moduleLocalName] [override]]` or `[[globalName]|[moduleLocalName]|[override]]`, where:
|
163 |
|
164 | - `globalName` - the name in the global object, for example `window.$` for a browser environment (**required**)
|
165 | - `moduleLocalName` - the name of method/variable/etc of the module (the module must export it) (**may be omitted**)
|
166 | - `override` - allows to override existing value in the global object (**may be omitted**)
|
167 |
|
168 | If `moduleLocalName` is not specified, it exposes the entire module to the global object, otherwise it exposes only the value of `moduleLocalName`.
|
169 |
|
170 | **src/index.js**
|
171 |
|
172 | ```js
|
173 | import _ from "underscore";
|
174 | ```
|
175 |
|
176 | **webpack.config.js**
|
177 |
|
178 | ```js
|
179 | module.exports = {
|
180 | module: {
|
181 | rules: [
|
182 | {
|
183 | test: require.resolve("jquery"),
|
184 | loader: "expose-loader",
|
185 | options: {
|
186 | // For `underscore` library, it can be `_.map map` or `_.map|map`
|
187 | exposes: "jquery",
|
188 | },
|
189 | },
|
190 | ],
|
191 | },
|
192 | };
|
193 | ```
|
194 |
|
195 | #### `object`
|
196 |
|
197 | Allows to use an object to describe an expose.
|
198 |
|
199 | ##### `globalName`
|
200 |
|
201 | Type:
|
202 |
|
203 | ```ts
|
204 | type globalName = string | Array<string>;
|
205 | ```
|
206 |
|
207 | Default: `undefined`
|
208 |
|
209 | The name in the global object. (**required**).
|
210 |
|
211 | **src/index.js**
|
212 |
|
213 | ```js
|
214 | import _ from "underscore";
|
215 | ```
|
216 |
|
217 | **webpack.config.js**
|
218 |
|
219 | ```js
|
220 | module.exports = {
|
221 | module: {
|
222 | rules: [
|
223 | {
|
224 | test: require.resolve("underscore"),
|
225 | loader: "expose-loader",
|
226 | options: {
|
227 | exposes: {
|
228 | // Can be `['_', 'filter']`
|
229 | globalName: "_.filter",
|
230 | moduleLocalName: "filter",
|
231 | },
|
232 | },
|
233 | },
|
234 | ],
|
235 | },
|
236 | };
|
237 | ```
|
238 |
|
239 | ##### `moduleLocalName`
|
240 |
|
241 | Type:
|
242 |
|
243 | ```ts
|
244 | type moduleLocalName = string;
|
245 | ```
|
246 |
|
247 | Default: `undefined`
|
248 |
|
249 | The name of method/variable/etc of the module (the module must export it).
|
250 | If `moduleLocalName` is specified, it exposes only the value of `moduleLocalName`.
|
251 |
|
252 | **src/index.js**
|
253 |
|
254 | ```js
|
255 | import _ from "underscore";
|
256 | ```
|
257 |
|
258 | **webpack.config.js**
|
259 |
|
260 | ```js
|
261 | module.exports = {
|
262 | module: {
|
263 | rules: [
|
264 | {
|
265 | test: require.resolve("underscore"),
|
266 | loader: "expose-loader",
|
267 | options: {
|
268 | exposes: {
|
269 | globalName: "_.filter",
|
270 | moduleLocalName: "filter",
|
271 | },
|
272 | },
|
273 | },
|
274 | ],
|
275 | },
|
276 | };
|
277 | ```
|
278 |
|
279 | ##### `override`
|
280 |
|
281 | Type:
|
282 |
|
283 | ```ts
|
284 | type override = boolean;
|
285 | ```
|
286 |
|
287 | Default: `false`
|
288 |
|
289 | By default loader does not override the existing value in the global object, because it is unsafe.
|
290 | In `development` mode, we throw an error if the value already present in the global object.
|
291 | But you can configure loader to override the existing value in the global object using this option.
|
292 |
|
293 | To force override the value that is already present in the global object you can set the `override` option to the `true` value.
|
294 |
|
295 | **src/index.js**
|
296 |
|
297 | ```js
|
298 | import $ from "jquery";
|
299 | ```
|
300 |
|
301 | **webpack.config.js**
|
302 |
|
303 | ```js
|
304 | module.exports = {
|
305 | module: {
|
306 | rules: [
|
307 | {
|
308 | test: require.resolve("jquery"),
|
309 | loader: "expose-loader",
|
310 | options: {
|
311 | exposes: {
|
312 | globalName: "$",
|
313 | override: true,
|
314 | },
|
315 | },
|
316 | },
|
317 | ],
|
318 | },
|
319 | };
|
320 | ```
|
321 |
|
322 | #### `array`
|
323 |
|
324 | **src/index.js**
|
325 |
|
326 | ```js
|
327 | import _ from "underscore";
|
328 | ```
|
329 |
|
330 | **webpack.config.js**
|
331 |
|
332 | ```js
|
333 | module.exports = {
|
334 | module: {
|
335 | rules: [
|
336 | {
|
337 | test: require.resolve("underscore"),
|
338 | loader: "expose-loader",
|
339 | options: {
|
340 | exposes: [
|
341 | "_.map map",
|
342 | {
|
343 | globalName: "_.filter",
|
344 | moduleLocalName: "filter",
|
345 | },
|
346 | {
|
347 | globalName: ["_", "find"],
|
348 | moduleLocalName: "myNameForFind",
|
349 | },
|
350 | ],
|
351 | },
|
352 | },
|
353 | ],
|
354 | },
|
355 | };
|
356 | ```
|
357 |
|
358 | It will expose **only** `map`, `filter` and `find` (under `myNameForFind` name) methods to the global object.
|
359 |
|
360 | In a browser these methods will be available under `windows._.map(..args)`, `windows._.filter(...args)` and `windows._.myNameForFind(...args)` methods.
|
361 |
|
362 | ## Contributing
|
363 |
|
364 | Please take a moment to read our contributing guidelines if you haven't yet done so.
|
365 |
|
366 | [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
367 |
|
368 | ## License
|
369 |
|
370 | [MIT](./LICENSE)
|
371 |
|
372 | [npm]: https://img.shields.io/npm/v/expose-loader.svg
|
373 | [npm-url]: https://npmjs.com/package/expose-loader
|
374 | [node]: https://img.shields.io/node/v/expose-loader.svg
|
375 | [node-url]: https://nodejs.org
|
376 | [deps]: https://david-dm.org/webpack-contrib/expose-loader.svg
|
377 | [deps-url]: https://david-dm.org/webpack-contrib/expose-loader
|
378 | [tests]: https://github.com/webpack-contrib/expose-loader/workflows/expose-loader/badge.svg
|
379 | [tests-url]: https://github.com/webpack-contrib/expose-loader/actions
|
380 | [cover]: https://codecov.io/gh/webpack-contrib/expose-loader/branch/master/graph/badge.svg
|
381 | [cover-url]: https://codecov.io/gh/webpack-contrib/expose-loader
|
382 | [chat]: https://badges.gitter.im/webpack/webpack.svg
|
383 | [chat-url]: https://gitter.im/webpack/webpack
|
384 | [size]: https://packagephobia.now.sh/badge?p=expose-loader
|
385 | [size-url]: https://packagephobia.now.sh/result?p=expose-loader
|