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