Host Environment

Easily detect what host environment your code is running in

Host Environment

Easily detect what host environment your code is running in

Build Status Coverage Status

npm Dependencies License

OS and Browser Compatibility

Host Environment is a universal JavaScript library that makes it easy to detect what host environment your code is running in. It lets you answer questions like:

Maybe some parts of your app are only available in Node and not in web browsers. Or maybe you need to determine whether to load a polyfill library. Or maybe you need to conditionally run tests in different environments. Whatever your reason, Host Environment can help.

Example

import host from "host-environment";

if (host.browser) {
  // Browser logic here

  if (host.browser.IE) {
    // Load a polyfill for Internet Explorer
  }
}

if (host.node) {
  // Node.js logic here

  if (host.node.version < 8) {
    // Load a polyfill for older versions of Node
  }

  if (host.os.windows) {
    // Windows-specific logic here
  }
}

Installation

Install using npm:

npm install host-environment

Usage

When using Host Environment in Node.js apps, you’ll probably want to use CommonJS syntax:

const host = require("host-environment");

When using a transpiler such as Babel or TypeScript, or a bundler such as Webpack or Rollup, you can use ECMAScript modules syntax instead:

import host from "host-environment";

Browser support

Host Environment supports recent versions of every major web browser. Older browsers may require Babel and/or polyfills.

To use Host Environment in a browser, you’ll need to use a bundling tool such as Webpack, Rollup, Parcel, or Browserify. Some bundlers may require a bit of configuration, such as setting browser: true in rollup-plugin-resolve.

API

host.global

When running in a web browser, host.global is a reference to the window object. When running in Node.js, it’s a reference to the global object.

host.os

This property is an object with the following structure:

{
  windows: false,       // Windows or Windows Phone
  mac: true,            // Mac OS or iOS
  linux: false          // Linux, Android, or other *nix platforms
}

Note: Only one of the properties will be true. All others are false.

host.env

This property is an object containing environment variables as key/value strings. When running in Node.js, it is set to process.env.

When running in a web browser, it is usually an empty object, since web browsers don’t have access to environment variables. However, when paired with tools like karma-host-environment, it’s possible to work-around this limitation and allow you to access environment variables in the browser.

{
  TERM: 'xterm-256color',
  SHELL: '/usr/local/bin/bash',
  USER: 'maciej',
  PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',
  PWD: '/Users/maciej',
  EDITOR: 'vim',
  SHLVL: '1',
  HOME: '/Users/maciej',
  LOGNAME: 'maciej',
  _: '/usr/local/bin/node'
}

host.node

This property is false when running in a web browser. When running in Node.js it is an object with the following structure:

{
  v7: true,             // The major version, as a boolean
  version: 7.3,         // The major.minor version, as a float
  majorVersion: 7,      // The major version, as an integer
  minorVersion: 3,      // The minor version, as an integer
  patchVersion: 24      // The patch version, as an integer
}

host.browser

This property is false when running in Node.js. When running in a browser it is an object with the following structure:

{
  chrome: {             // false if not Chrome
    v58: true,          // The major version, as a boolean
    version: 58.4,      // The major.minor version, as a float
    majorVersion: 58,   // The major version, as an integer
    minorVersion: 4,    // The minor version, as an integer
    patchVersion: 3029, // The patch version, as an integer
    mobile: false,      // true on mobile
  },
  firefox: false,       // An object like above if running in Firefox
  safari: false,        // An object like above if running in Safari
  edge: false,          // An object like above if running in Edge
  IE: false,            // An object like above if running in Internet Explorer
  mobile: false,        // true for any mobile browser (iOS, Android, Windows Phone, etc)
}

Note: Only one of the browser properties will be an object. All others are false.

Contributing

Contributions, enhancements, and bug-fixes are welcome! File an issue on GitHub and submit a pull request.

Building

To build the project locally on your computer:

  1. Clone this repo
    git clone https://github.com/JS-DevTools/host-environment.git

  2. Install dependencies
    npm install

  3. Build the code
    npm run build

  4. Run the tests
    npm test

License

host-environment is 100% free and open-source, under the MIT license. Use it however you want.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❤

Travis CI SauceLabs Coveralls