https://github.com/peerigon/legacy-loader
Webpack loader that prevents scripts from extending the window object.
https://github.com/peerigon/legacy-loader
Last synced: 11 months ago
JSON representation
Webpack loader that prevents scripts from extending the window object.
- Host: GitHub
- URL: https://github.com/peerigon/legacy-loader
- Owner: peerigon
- License: unlicense
- Created: 2015-02-02T13:49:22.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2020-08-27T12:57:07.000Z (almost 6 years ago)
- Last Synced: 2025-08-09T09:47:28.502Z (11 months ago)
- Language: JavaScript
- Homepage:
- Size: 28.3 KB
- Stars: 12
- Watchers: 16
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# legacy-loader
**[Webpack](http://webpack.github.io/) loader that prevents scripts from extending the window object**
[](https://travis-ci.org/peerigon/legacy-loader)
[](https://david-dm.org/peerigon/legacy-loader)
[](https://coveralls.io/r/peerigon/legacy-loader?branch=master)
Use this loader to cope with legacy scripts that extend the window object instead of using AMD or CommonJS.
**Please note: There is a major issue with the current approach of this loader, see [#1](https://github.com/peerigon/legacy-loader/issues/1). Use at your own risk!**
## Installation
[](https://npmjs.org/package/legacy-loader)
## Usage
### Basic example
Imagine you've downloaded `some-legacy-script` from npm which looks like
```javascript
window.someLegacyScript = function () {
console.log("Yay!");
};
```
Now just run `npm i legacy-loader --save` and configure your `webpack.config.js` like this
```javascript
module.exports = {
module: {
loaders: [
{
test: /[\/\\]node_modules[\/\\]some-legacy-script[\/\\]index\.js$/,
loader: "legacy",
},
],
},
};
```
then you can do
```javascript
var someLegacyScript = require("some-legacy-script");
someLegacyScript(); // prints 'Yay!'
window.someLegacyScript; // undefined
```
### Auto export
The **legacy-loader** exports a single value via `module.exports` when your legacy script did only add one
property to the window object. If it added two or more, an object is returned instead:
```javascript
// node_modules/some-legacy-script/index.js
window.propertyA = true;
window.propertyB = false;
```
```javascript
// app.js
var someLegacyScript = require("some-legacy-script");
someLegacyScript.propertyA; // true
someLegacyScript.propertyB; // false
window.propertyA; // undefined
window.propertyB; // undefined
```
### Specific exports
When your legacy script adds two or more properties, but you're still just interested in one particular property,
you can also pass a property name:
```javascript
// webpack.config.js
...
{
test: /[\/\\]node_modules[\/\\]some-legacy-script[\/\\]index\.js$/,
loader: "legacy?exports=propertyA"
}
...
```
```javascript
// app.js
var someLegacyScript = require("some-legacy-script");
someLegacyScript; // true -> propertyA
```
### Publish
Sometimes other libraries are relying on a particular global variable (like jQuery plugins rely on `$`). Then you should
first consider using the [imports-loader](https://github.com/webpack/imports-loader) to inject that variable into the
private module scope. If this is not an option for you (e.g. because you're not loading this module via webpack),
you can decide to publish a single property back to the window object.
```javascript
// webpack.config.js
...
{
test: /[\/\\]node_modules[\/\\]some-legacy-script[\/\\]index\.js$/,
loader: "legacy?publish=propertyB"
}
...
```
```javascript
// app.js
var someLegacyScript = require("some-legacy-script");
someLegacyScript.propertyA; // true
someLegacyScript.propertyB; // false
window.propertyA; // undefined
window.propertyB; // false
```
## Under the hood
The **legacy-loader** creates a window shim by inheriting from window via `Object.create(window)`. Thus the
legacy script receives a window-like object, without being able to extend it. Of course, this approach has
the usual limitations implied by the prototype inheritance (such as iterating over `window` while checking for
`hasOwnProperty`).
## Contributing
From opening a bug report to creating a pull request: **every contribution is appreciated and welcome**. If you're planing to implement a new feature or change the api please create an issue first. This way we can ensure that your precious work is not in vain.
All pull requests should have 100% test coverage (with notable exceptions) and need to pass all tests.
- Call `npm test` to run the unit tests
- Call `npm run coverage` to check the test coverage (using [istanbul](https://github.com/gotwarlost/istanbul))
## License
Unlicense
## Sponsors
[
](https://peerigon.com)