Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/webpack-contrib/expose-loader
Expose Loader
https://github.com/webpack-contrib/expose-loader
webpack-loader
Last synced: 1 day ago
JSON representation
Expose Loader
- Host: GitHub
- URL: https://github.com/webpack-contrib/expose-loader
- Owner: webpack-contrib
- License: mit
- Created: 2013-02-10T20:20:08.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2024-10-29T07:46:52.000Z (6 days ago)
- Last Synced: 2024-10-29T23:50:29.330Z (5 days ago)
- Topics: webpack-loader
- Language: JavaScript
- Homepage:
- Size: 2.18 MB
- Stars: 546
- Watchers: 15
- Forks: 73
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[![npm][npm]][npm-url]
[![node][node]][node-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![discussion][discussion]][discussion-url]
[![size][size]][size-url]
# expose-loader
The `expose-loader` loader allows to expose a module (in whole or in part) to global object (`self`, `window` and `global`).
For further hints on compatibility issues, check out [Shimming](https://webpack.js.org/guides/shimming/) of the official docs.
## Getting Started
To begin, you'll need to install `expose-loader`:
```console
npm install expose-loader --save-dev
```
or
```console
yarn add -D expose-loader
```
or
```console
pnpm add -D expose-loader
```
(If you're using WebPack 4, install `expose-loader@1` and follow the [corresponding instructions](https://v4.webpack.js.org/loaders/expose-loader/) instead.)
Then you can use the `expose-loader` using two approaches.
## Inline
The `|` or `%20` (space) allow to separate the `globalName`, `moduleLocalName` and `override` of expose.
The documentation and syntax examples can be read [here](#syntax).
> [!WARNING]
>
> `%20` is space in a query string, because you can't use spaces in URLs
```js
import $ from "expose-loader?exposes=$,jQuery!jquery";
//
// Adds the `jquery` to the global object under the names `$` and `jQuery`
```
```js
import { concat } from "expose-loader?exposes=_.concat!lodash/concat";
//
// Adds the `lodash/concat` to the global object under the name `_.concat`
```
```js
import {
map,
reduce,
} from "expose-loader?exposes=_.map|map,_.reduce|reduce!underscore";
//
// Adds the `map` and `reduce` method from `underscore` to the global object under the name `_.map` and `_.reduce`
```
## Using Configuration
**src/index.js**
```js
import $ from "jquery";
```
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: require.resolve("jquery"),
loader: "expose-loader",
options: {
exposes: ["$", "jQuery"],
},
},
{
test: require.resolve("underscore"),
loader: "expose-loader",
options: {
exposes: [
"_.map|map",
{
globalName: "_.reduce",
moduleLocalName: "reduce",
},
{
globalName: ["_", "filter"],
moduleLocalName: "filter",
},
],
},
},
],
},
};
```
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).
`require.resolve` gives you the absolute path to the module (`"/.../app/node_modules/jquery/dist/jquery.js"`).
So the expose only applies to the `jquery` module. And it's only exposed when used in the bundle.
And run `webpack` via your preferred method.
## Options
| Name | Type | Default | Description |
| :---------------------------------: | :---------------------------------------: | :---------: | :----------------------------- |
| **[`exposes`](#exposes)** | `{String\|Object\|Array}` | `undefined` | List of exposes |
| **[`globalObject`](#globalObject)** | `String` | `undefined` | Object used for global context |
### `exposes`
Type:
```ts
type exposes =
| string
| {
globalName: string | Array;
moduleLocalName?: string;
override?: boolean;
}
| Array<
| string
| {
globalName: string | Array;
moduleLocalName?: string;
override?: boolean;
}
>;
```
Default: `undefined`
List of exposes.
#### `string`
Allows to use a string to describe an expose.
##### `syntax`
The `|` or `%20` (space) allow to separate the `globalName`, `moduleLocalName` and `override` of expose.
String syntax - `[[globalName] [moduleLocalName] [override]]` or `[[globalName]|[moduleLocalName]|[override]]`, where:
- `globalName` - the name in the global object, for example `window.$` for a browser environment (**required**)
- `moduleLocalName` - the name of method/variable/etc of the module (the module must export it) (**may be omitted**)
- `override` - allows to override existing value in the global object (**may be omitted**)
If `moduleLocalName` is not specified, it exposes the entire module to the global object, otherwise it exposes only the value of `moduleLocalName`.
**src/index.js**
```js
import $ from "jquery";
import _ from "underscore";
```
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: require.resolve("jquery"),
loader: "expose-loader",
options: {
// For `underscore` library, it can be `_.map map` or `_.map|map`
exposes: "$",
// To access please use `window.$` or `globalThis.$`
},
},
{
// test: require.resolve("jquery"),
test: /node_modules[/\\]underscore[/\\]modules[/\\]index-all\.js$/,
loader: "expose-loader",
type: "javascript/auto",
options: {
// For `underscore` library, it can be `_.map map` or `_.map|map`
exposes: "_",
// To access please use `window._` or `globalThis._`
},
},
],
},
};
```
#### `object`
Allows to use an object to describe an expose.
##### `globalName`
Type:
```ts
type globalName = string | Array;
```
Default: `undefined`
The name in the global object. (**required**).
**src/index.js**
```js
import _ from "underscore";
```
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: /node_modules[/\\]underscore[/\\]modules[/\\]index-all\.js$/,
loader: "expose-loader",
type: "javascript/auto",
options: {
exposes: {
// Can be `['_', 'filter']`
globalName: "_.filter",
moduleLocalName: "filter",
},
},
},
],
},
};
```
##### `moduleLocalName`
Type:
```ts
type moduleLocalName = string;
```
Default: `undefined`
The name of method/variable/etc of the module (the module must export it).
If `moduleLocalName` is specified, it exposes only the value of `moduleLocalName`.
**src/index.js**
```js
import _ from "underscore";
```
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: /node_modules[/\\]underscore[/\\]modules[/\\]index-all\.js$/,
loader: "expose-loader",
type: "javascript/auto",
options: {
exposes: {
globalName: "_.filter",
moduleLocalName: "filter",
},
},
},
],
},
};
```
##### `override`
Type:
```ts
type override = boolean;
```
Default: `false`
By default, loader does not override the existing value in the global object, because it is unsafe.
In `development` mode, we throw an error if the value already present in the global object.
But you can configure loader to override the existing value in the global object using this option.
To force override the value that is already present in the global object you can set the `override` option to the `true` value.
**src/index.js**
```js
import $ from "jquery";
```
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: require.resolve("jquery"),
loader: "expose-loader",
options: {
exposes: {
globalName: "$",
override: true,
},
},
},
],
},
};
```
#### `array`
**src/index.js**
```js
import _ from "underscore";
```
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: /node_modules[/\\]underscore[/\\]modules[/\\]index-all\.js$/,
loader: "expose-loader",
type: "javascript/auto",
options: {
exposes: [
"_.map map",
{
globalName: "_.filter",
moduleLocalName: "filter",
},
{
globalName: ["_", "find"],
moduleLocalName: "myNameForFind",
},
],
},
},
],
},
};
```
It will expose **only** `map`, `filter` and `find` (under `myNameForFind` name) methods to the global object.
In a browser these methods will be available under `windows._.map(..args)`, `windows._.filter(...args)` and `windows._.myNameForFind(...args)` methods.
### `globalObject`
```ts
type globalObject = string;
```
Default: `undefined`
Object used for global context
```js
import _ from "underscore";
```
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: /node_modules[/\\]underscore[/\\]modules[/\\]index-all\.js$/,
loader: "expose-loader",
type: "javascript/auto",
options: {
exposes: [
{
globalName: "_",
},
],
globalObject: "this",
},
},
],
},
};
```
## Examples
### Expose a local module
**index.js**
```js
import { method1 } from "./my-module.js";
```
**my-module.js**
```js
function method1() {
console.log("method1");
}
function method2() {
console.log("method1");
}
export { method1, method2 };
```
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: /my-module\.js$/,
loader: "expose-loader",
options: {
exposes: "mod",
// // To access please use `window.mod` or `globalThis.mod`
},
},
],
},
};
```
## Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.
[CONTRIBUTING](./.github/CONTRIBUTING.md)
## License
[MIT](./LICENSE)
[npm]: https://img.shields.io/npm/v/expose-loader.svg
[npm-url]: https://npmjs.com/package/expose-loader
[node]: https://img.shields.io/node/v/expose-loader.svg
[node-url]: https://nodejs.org
[tests]: https://github.com/webpack-contrib/expose-loader/workflows/expose-loader/badge.svg
[tests-url]: https://github.com/webpack-contrib/expose-loader/actions
[cover]: https://codecov.io/gh/webpack-contrib/expose-loader/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/expose-loader
[discussion]: https://img.shields.io/github/discussions/webpack/webpack
[discussion-url]: https://github.com/webpack/webpack/discussions
[size]: https://packagephobia.now.sh/badge?p=expose-loader
[size-url]: https://packagephobia.now.sh/result?p=expose-loader