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