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 | Then you can use the `expose-loader` using two approaches.
|
30 |
|
31 | ## Inline
|
32 |
|
33 | The `|` or `%20` (space) allow to separate the `globalName`, `moduleLocalName` and `override` of expose.
|
34 | The documentation and syntax examples can be read [here](#syntax).
|
35 |
|
36 | > ⚠ `%20` is space in a query string, because you can't use spaces in URLs
|
37 |
|
38 | ```js
|
39 | import $ from "expose-loader?exposes=$,jQuery!jquery";
|
40 | //
|
41 | // Adds the `jquery` to the global object under the names `$` and `jQuery`
|
42 | ```
|
43 |
|
44 | ```js
|
45 | import { concat } from "expose-loader?exposes=_.concat!lodash/concat";
|
46 | //
|
47 | // Adds the `lodash/concat` to the global object under the name `_.concat`
|
48 | ```
|
49 |
|
50 | ```js
|
51 | import {
|
52 | map,
|
53 | reduce,
|
54 | } from "expose-loader?exposes=_.map|map,_.reduce|reduce!underscore";
|
55 | //
|
56 | // Adds the `map` and `reduce` method from `underscore` to the global object under the name `_.map` and `_.reduce`
|
57 | ```
|
58 |
|
59 | ## Using Configuration
|
60 |
|
61 | **src/index.js**
|
62 |
|
63 | ```js
|
64 | import $ from "jquery";
|
65 | ```
|
66 |
|
67 | **webpack.config.js**
|
68 |
|
69 | ```js
|
70 | module.exports = {
|
71 | module: {
|
72 | rules: [
|
73 | {
|
74 | test: require.resolve("jquery"),
|
75 | loader: "expose-loader",
|
76 | options: {
|
77 | exposes: ["$", "jQuery"],
|
78 | },
|
79 | },
|
80 | {
|
81 | test: require.resolve("underscore"),
|
82 | loader: "expose-loader",
|
83 | options: {
|
84 | exposes: [
|
85 | "_.map|map",
|
86 | {
|
87 | globalName: "_.reduce",
|
88 | moduleLocalName: "reduce",
|
89 | },
|
90 | {
|
91 | globalName: ["_", "filter"],
|
92 | moduleLocalName: "filter",
|
93 | },
|
94 | ],
|
95 | },
|
96 | },
|
97 | ],
|
98 | },
|
99 | };
|
100 | ```
|
101 |
|
102 | 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).
|
103 | `require.resolve` gives you the absolute path to the module (`"/.../app/node_modules/jquery/dist/jquery.js"`).
|
104 | So the expose only applies to the `jquery` module. And it's only exposed when used in the bundle.
|
105 |
|
106 | And run `webpack` via your preferred method.
|
107 |
|
108 | ## Options
|
109 |
|
110 | | Name | Type | Default | Description |
|
111 | | :-----------------------: | :---------------------------------------: | :---------: | :-------------- |
|
112 | | **[`exposes`](#exposes)** | `{String\|Object\|Array<String\|Object>}` | `undefined` | List of exposes |
|
113 |
|
114 | ### `exposes`
|
115 |
|
116 | Type: `String|Object|Array<String|Object>`
|
117 | Default: `undefined`
|
118 |
|
119 | List of exposes.
|
120 |
|
121 | #### `String`
|
122 |
|
123 | Allows to use a string to describe an expose.
|
124 |
|
125 | ##### `Syntax`
|
126 |
|
127 | The `|` or `%20` (space) allow to separate the `globalName`, `moduleLocalName` and `override` of expose.
|
128 |
|
129 | String syntax - `[[globalName] [moduleLocalName] [override]]` or `[[globalName]|[moduleLocalName]|[override]]`, where:
|
130 |
|
131 | - `globalName` - the name in the global object, for example `window.$` for a browser environment (**required**)
|
132 | - `moduleLocalName` - the name of method/variable/etc of the module (the module must export it) (**may be omitted**)
|
133 | - `override` - allows to override existing value in the global object (**may be omitted**)
|
134 |
|
135 | If `moduleLocalName` is not specified, it exposes the entire module to the global object, otherwise it exposes only the value of `moduleLocalName`.
|
136 |
|
137 | **src/index.js**
|
138 |
|
139 | ```js
|
140 | import _ from "underscore";
|
141 | ```
|
142 |
|
143 | **webpack.config.js**
|
144 |
|
145 | ```js
|
146 | module.exports = {
|
147 | module: {
|
148 | rules: [
|
149 | {
|
150 | test: require.resolve("jquery"),
|
151 | loader: "expose-loader",
|
152 | options: {
|
153 | // For `underscore` library, it can be `_.map map` or `_.map|map`
|
154 | exposes: "jquery",
|
155 | },
|
156 | },
|
157 | ],
|
158 | },
|
159 | };
|
160 | ```
|
161 |
|
162 | #### `Object`
|
163 |
|
164 | Allows to use an object to describe an expose.
|
165 |
|
166 | ##### `globalName`
|
167 |
|
168 | Type: `String|Array<String>`
|
169 | Default: `undefined`
|
170 |
|
171 | The name in the global object. (**required**).
|
172 |
|
173 | **src/index.js**
|
174 |
|
175 | ```js
|
176 | import _ from "underscore";
|
177 | ```
|
178 |
|
179 | **webpack.config.js**
|
180 |
|
181 | ```js
|
182 | module.exports = {
|
183 | module: {
|
184 | rules: [
|
185 | {
|
186 | test: require.resolve("underscore"),
|
187 | loader: "expose-loader",
|
188 | options: {
|
189 | exposes: {
|
190 | // Can be `['_', 'filter']`
|
191 | globalName: "_.filter",
|
192 | moduleLocalName: "filter",
|
193 | },
|
194 | },
|
195 | },
|
196 | ],
|
197 | },
|
198 | };
|
199 | ```
|
200 |
|
201 | ##### `moduleLocalName`
|
202 |
|
203 | Type: `String`
|
204 | Default: `undefined`
|
205 |
|
206 | The name of method/variable/etc of the module (the module must export it).
|
207 | If `moduleLocalName` is specified, it exposes only the value of `moduleLocalName`.
|
208 |
|
209 | **src/index.js**
|
210 |
|
211 | ```js
|
212 | import _ from "underscore";
|
213 | ```
|
214 |
|
215 | **webpack.config.js**
|
216 |
|
217 | ```js
|
218 | module.exports = {
|
219 | module: {
|
220 | rules: [
|
221 | {
|
222 | test: require.resolve("underscore"),
|
223 | loader: "expose-loader",
|
224 | options: {
|
225 | exposes: {
|
226 | globalName: "_.filter",
|
227 | moduleLocalName: "filter",
|
228 | },
|
229 | },
|
230 | },
|
231 | ],
|
232 | },
|
233 | };
|
234 | ```
|
235 |
|
236 | ##### `override`
|
237 |
|
238 | Type: `Boolean`
|
239 | Default: `false`
|
240 |
|
241 | By default loader does not override the existing value in the global object, because it is unsafe.
|
242 | In `development` mode, we throw an error if the value already present in the global object.
|
243 | But you can configure loader to override the existing value in the global object using this option.
|
244 |
|
245 | To force override the value that is already present in the global object you can set the `override` option to the `true` value.
|
246 |
|
247 | **src/index.js**
|
248 |
|
249 | ```js
|
250 | import $ from "jquery";
|
251 | ```
|
252 |
|
253 | **webpack.config.js**
|
254 |
|
255 | ```js
|
256 | module.exports = {
|
257 | module: {
|
258 | rules: [
|
259 | {
|
260 | test: require.resolve("jquery"),
|
261 | loader: "expose-loader",
|
262 | options: {
|
263 | exposes: {
|
264 | globalName: "$",
|
265 | override: true,
|
266 | },
|
267 | },
|
268 | },
|
269 | ],
|
270 | },
|
271 | };
|
272 | ```
|
273 |
|
274 | #### `Array`
|
275 |
|
276 | **src/index.js**
|
277 |
|
278 | ```js
|
279 | import _ from "underscore";
|
280 | ```
|
281 |
|
282 | **webpack.config.js**
|
283 |
|
284 | ```js
|
285 | module.exports = {
|
286 | module: {
|
287 | rules: [
|
288 | {
|
289 | test: require.resolve("underscore"),
|
290 | loader: "expose-loader",
|
291 | options: {
|
292 | exposes: [
|
293 | "_.map map",
|
294 | {
|
295 | globalName: "_.filter",
|
296 | moduleLocalName: "filter",
|
297 | },
|
298 | {
|
299 | globalName: ["_", "find"],
|
300 | moduleLocalName: "myNameForFind",
|
301 | },
|
302 | ],
|
303 | },
|
304 | },
|
305 | ],
|
306 | },
|
307 | };
|
308 | ```
|
309 |
|
310 | It will expose **only** `map`, `filter` and `find` (under `myNameForFind` name) methods to the global object.
|
311 |
|
312 | In a browser these methods will be available under `windows._.map(..args)`, `windows._.filter(...args)` and `windows._.myNameForFind(...args)` methods.
|
313 |
|
314 | ## Contributing
|
315 |
|
316 | Please take a moment to read our contributing guidelines if you haven't yet done so.
|
317 |
|
318 | [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
319 |
|
320 | ## License
|
321 |
|
322 | [MIT](./LICENSE)
|
323 |
|
324 | [npm]: https://img.shields.io/npm/v/expose-loader.svg
|
325 | [npm-url]: https://npmjs.com/package/expose-loader
|
326 | [node]: https://img.shields.io/node/v/expose-loader.svg
|
327 | [node-url]: https://nodejs.org
|
328 | [deps]: https://david-dm.org/webpack-contrib/expose-loader.svg
|
329 | [deps-url]: https://david-dm.org/webpack-contrib/expose-loader
|
330 | [tests]: https://github.com/webpack-contrib/expose-loader/workflows/expose-loader/badge.svg
|
331 | [tests-url]: https://github.com/webpack-contrib/expose-loader/actions
|
332 | [cover]: https://codecov.io/gh/webpack-contrib/expose-loader/branch/master/graph/badge.svg
|
333 | [cover-url]: https://codecov.io/gh/webpack-contrib/expose-loader
|
334 | [chat]: https://badges.gitter.im/webpack/webpack.svg
|
335 | [chat-url]: https://gitter.im/webpack/webpack
|
336 | [size]: https://packagephobia.now.sh/badge?p=expose-loader
|
337 | [size-url]: https://packagephobia.now.sh/result?p=expose-loader
|