Host Environment

Easily detect what host environment your code is running in

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:

• Am I running in Node.js or a web browser?
• Is this Node 8.x or newer?
• Are we in Internet Explorer?
• Is this a Windows computer?

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
  }
}

Related Projects

• karma-host-environment
  Access environment variables and other system info in your browser tests.

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 ❤