window-var
Version:
Acquires global `window` var in a browserify-compatible way.
208 lines (168 loc) • 16.7 kB
Markdown
<h1 align="center" style="text-align:center;">Window Var</h1>
<p align="center" style="text-align:center;">Acquires global `window` var in a browserify-compatible way.</p>
<p align="center" style="text-align:center;">
<a href="https://www.npmjs.com/package/window-var"><img src="https://nodei.co/npm/window-var.png?downloads=true&downloadRank=true&stars=true" alt="npm overview" height="69" valign="middle" style="height:69px; vertical-align:middle;" /></a><br />
<a href="https://github.com/src-works/window-var/blob/master/CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.0.11-blue.svg" alt="latest version" height="20" valign="middle" style="height:20px; vertical-align:middle;" /></a> <a href="https://github.com/src-works/window-var/blob/master/LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license" height="20" valign="middle" style="height:20px; vertical-align:middle;" /></a> <a href="https://github.com/src-works/window-var/blob/master/src/scripts/js/index.js"><img src="https://img.shields.io/github/size/src-works/window-var/src/scripts/js/index.js.svg" alt="main script size" height="20" valign="middle" style="height:20px; vertical-align:middle;" /></a> <a href="https://github.com/src-works/window-var/blob/master/dist/scripts/ts/types/index.d.ts"><img src="https://img.shields.io/badge/%f0%9f%93%98-typescript%2fjs-2882C3.svg" alt="typescript/js" height="20" valign="middle" style="height:20px; vertical-align:middle;" /></a> <a href="https://github.com/src-works/window-var/issues"><img src="https://img.shields.io/github/issues/src-works/window-var.svg" alt="open issues" height="20" valign="middle" style="height:20px; vertical-align:middle;" /></a><br />
<a href="https://greenkeeper.io/"><img src="https://img.shields.io/badge/greenkeeper-enabled-brightgreen.svg" alt="greenkeeper" height="20" valign="middle" style="height:20px; vertical-align:middle;" /></a> <a href="https://david-dm.org/src-works/window-var"><img src="https://img.shields.io/david/src-works/window-var.svg" alt="dependency status" height="20" valign="middle" style="height:20px; vertical-align:middle;" /></a> <a href="https://twitter.com/_src_works"><img src="https://img.shields.io/twitter/follow/_src_works.svg?style=social&label=Follow%20%40_src_works" alt="follow on twitter" height="20" valign="middle" style="height:20px; vertical-align:middle;" /></a> <a href="https://github.com/src-works/window-var"><img src="https://img.shields.io/github/followers/src-works.svg?style=social&label=Follow" alt="follow on github" height="20" valign="middle" style="height:20px; vertical-align:middle;" /></a> <a href="https://github.com/src-works/window-var/fork"><img src="https://img.shields.io/github/forks/src-works/window-var.svg?style=social&label=Fork" alt="fork" height="20" valign="middle" style="height:20px; vertical-align:middle;" /></a>
</p>
<p align="center" style="text-align:center;">
<a href="https://src.works/donate?utm_source=repo&utm_medium=organic&utm_term=src-works%2Fwindow-var&utm_campaign=donate%3Aserver-side&utm_content=sub-header"><img src="https://src.works/wp-content/uploads/2017/07/dby-donate.svg?v=0.0.1" alt="developed by ‹src.works/›" width="100%" height="auto" style="width:100%; height:auto;" /></a>
</p>
## Project Overview
When your project requires a DOM; i.e., a `window.document` reference. Using this library maximizes compatibility across a variety of browser-like environments. Instead of hard-coding references to `window`, use this package to work out the `window` reference dynamically; i.e., in case your web-based project ends up being used in places other than a traditional web browser.
For example, in an Electron app, in a JSDOM-related project, or in a project that doesn't expose `window` as `window`, but through another global variable, such as: `global`, `self`, or `this`.
## Installation Options
### Install via <img src="https://src.works/wp-content/uploads/2017/05/npm.svg?v=0.0.1" alt="NPM" valign="middle" width="auto" height="20" style="vertical-align:middle; width:auto; height:20px;" /> [package](https://www.npmjs.com/package/window-var)
```bash
$ npm install window-var --save;
```
### Or install via <img src="https://src.works/wp-content/uploads/2017/06/yarn.svg?v=0.0.1" alt="Yarn" valign="middle" width="auto" height="24" style="vertical-align:middle; width:auto; height:24px;" /> Yarn [package](https://yarnpkg.com/en/package/window-var)
```bash
$ yarn add window-var;
```
## Using the Package
The following works when your package runs from a browser-like environment; i.e., when one of `window`, `global`, `self`, or `this` points to a Window object in the current environment.
```js
import {win} from 'window-var';
console.log(win.document.URL);
```
Which is a much shorter version of this longer equivalency.
```js
console.log((() => {
if (typeof window !== 'undefined') {
return window;
} else if (typeof global !== 'undefined') {
return global;
} else if (typeof self !== 'undefined') {
return self;
} else {
return this;
}
})().document.URL);
```
### Alternate Imports
This way allows you to work out the window var later by calling the `.get()` method on-demand.
```js
import win from 'window-var';
console.log(win.get().document.URL);
```
This is basically the same as the previous example, but a little cleaner.
```js
import {get as win} from 'window-var';
console.log(win().document.URL);
```
---
<p align="center" style="text-align:center;">
<a href="https://src.works/subscribe?utm_source=repo&utm_medium=organic&utm_term=src-works%2Fwindow-var&utm_campaign=donate%3Aserver-side&utm_content=built-with:image"><img src="https://src.works/wp-content/uploads/2017/08/built-with.svg?v=0.0.1" alt="Built with TypeScript/JavaScript, Babel, NodeJS, NPM, and Sass" width="100%" height="auto" style="width:100%; height:auto;" /></a>
</p>
## Commercial Use
<img src="https://www.gravatar.com/avatar/c8e0057f78fa5b54326cd437494b87e9?s=256&v=0.0.1" alt="@jaswrks" align="right" width="12%" height="auto" hspace="30" style="float:right; width:12%; height:auto; margin-left:30px;" />
This software is created, documented and maintained by [Jason Caldwell](https://twitter.com/jaswrks) ([`@jaswrks`](https://twitter.com/jaswrks)) and a small team of talented developers at [‹src.works/›](https://src.works). It's open source, but if you use it commercially, please [**pay what you can**](https://src.works/donate?utm_source=repo&utm_medium=organic&utm_term=src-works%2Fwindow-var&utm_campaign=donate%3Aserver-side&utm_content=commercial-use).
## Development Channels
Always use the latest stable version in production. If you want upcoming changes ahead of time use the `@dev` or `@rc` tag, but please do so at your own risk. The `@dev` and `@rc` tags are potentially unstable at various times throughout a development cycle, and therefore should not be used in production.
<table width="100%" align="center" style="width:100%; margin-left:auto; margin-right:auto;">
<thead>
<tr>
<th align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">Channel</th>
<th align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">NPM Tag</th>
<th align="center" valign="middle" width="100%" style="text-align:center; vertical-align:middle; width:100%;">Description</th>
<th align="center" valign="middle" width="150" nowrap style="text-align:center; vertical-align:middle; width:150px;"><a href="http://semver.org/">SemVer</a></th>
<th align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">GitHub</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">Hackers</td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@dev/">@dev</a></td>
<td align="center" valign="middle" style="text-align:center; vertical-align:middle;"><strong>Latest Bleeding Edge</strong><br />potentially-unstable</td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@dev/"><img src="https://img.shields.io/npm/v/window-var/dev.svg" alt="Release Tag" valign="middle" style="vertical-align:middle;" /></a></td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://github.com/src-works/window-var/tree/master">master</a> (<a href="https://github.com/src-works/window-var/pulls">PRs</a>)</td>
</tr>
<tr>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">Lab Rats</td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@rc/">@rc</a></td>
<td align="center" valign="middle" style="text-align:center; vertical-align:middle;"><strong>Next Release Candidate</strong><br />upcoming semi-stable release</td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@rc/"><img src="https://img.shields.io/npm/v/window-var/rc.svg" alt="Release Tag" valign="middle" style="vertical-align:middle;" /></a></td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://github.com/src-works/window-var/releases">releases</a></td>
</tr>
<tr>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><strong>Everyone</strong></td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@latest/">@latest</a></td>
<td align="center" valign="middle" style="text-align:center; vertical-align:middle;"><strong>Latest Stable Version</strong><br />highly recommended</td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@latest/"><img src="https://img.shields.io/npm/v/window-var/latest.svg" alt="Release Tag" valign="middle" style="vertical-align:middle;" /></a></td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://github.com/src-works/window-var/releases">releases</a></td>
</tr>
</tbody>
</table>
## NPM Consumption Examples
<table width="100%" align="center" style="width:100%; margin-left:auto; margin-right:auto;">
<thead>
<tr>
<th align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">Channel</th>
<th align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">NPM Tag</th>
<th align="center" valign="middle" width="100%" style="text-align:center; vertical-align:middle; width:100%;">NPM package.json</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">Hackers</td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@dev/">@dev</a></td>
<td align="center" valign="middle" style="text-align:center; vertical-align:middle;"><code>"window-var": "dev"</code></td>
</tr>
<tr>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">Lab Rats</td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@rc/">@rc</a></td>
<td align="center" valign="middle" style="text-align:center; vertical-align:middle;"><code>"window-var": "rc"</code></td>
</tr>
<tr>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><strong>Everyone</strong></td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@latest/">@latest</a></td>
<td align="center" valign="middle" style="text-align:center; vertical-align:middle;"><code>"window-var": "latest"</code></td>
</tr>
<tr>
<td align="center" valign="middle" colspan="2" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><strong>Latest Stable Version</strong></td>
<td align="center" valign="middle" style="text-align:center; vertical-align:middle;"><code>"window-var": "^1.0.11"</code></td>
</tr>
</tbody>
</table>
<table width="100%" align="center" style="width:100%; margin-left:auto; margin-right:auto;">
<thead>
<tr>
<th align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">Channel</th>
<th align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">NPM Tag</th>
<th align="center" valign="middle" width="100%" style="text-align:center; vertical-align:middle; width:100%;">NPM Install</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">Hackers</td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@dev/">@dev</a></td>
<td align="center" valign="middle" style="text-align:center; vertical-align:middle;"><code>npm install window-var@dev</code></td>
</tr>
<tr>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;">Lab Rats</td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@rc/">@rc</a></td>
<td align="center" valign="middle" style="text-align:center; vertical-align:middle;"><code>npm install window-var@rc</code></td>
</tr>
<tr>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><strong>Everyone</strong></td>
<td align="center" valign="middle" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><a href="https://unpkg.com/window-var@latest/">@latest</a></td>
<td align="center" valign="middle" style="text-align:center; vertical-align:middle;"><code>npm install window-var@latest</code></td>
</tr>
<tr>
<td align="center" valign="middle" colspan="2" nowrap style="text-align:center; vertical-align:middle; white-space:nowrap;"><strong>Latest Stable Version</strong></td>
<td align="center" valign="middle" style="text-align:center; vertical-align:middle;"><code>npm install window-var</code></td>
</tr>
</tbody>
</table>
## MIT License
For full details see: [LICENSE.txt](https://github.com/src-works/window-var/blob/master/LICENSE.txt)
## Changelog
For full details see: [CHANGELOG.md](https://github.com/src-works/window-var/blob/master/CHANGELOG.md)
## Semantic Versioning
New versions are released following [semver.org](http://semver.org/) guidelines.
## Pull Requests Welcome
<a href="https://github.com/src-works/window-var/fork"><img src="https://img.shields.io/github/forks/src-works/window-var.svg?style=social&label=Fork" alt="fork" height="20" valign="middle" style="height:20px; vertical-align:middle;" /></a> the `master` branch at GitHub and submit your changes for review.
<p align="center" style="text-align:center;">
<a href="https://src.works/subscribe?utm_source=repo&utm_medium=organic&utm_term=src-works%2Fwindow-var&utm_campaign=donate%3Aserver-side&utm_content=lab-rats:subscribe"><img src="https://src.works/wp-content/uploads/2017/05/lab-rats-subscribe.svg?v=0.0.1" alt="Lab Rats Subscribe" width="100%" height="auto" style="width:100%; height:auto;" /></a>
</p>